Hosted Cards

A hosted card is a single-use card-token that is returned by a successful checkout using a Payment Session. When using an end to end transaction, the Hosted Payments Page uses the hosted card to immediately create a transaction for the concluded payment session.

You have the option to disable end-to-end transactions and have the Hosted Payments Page post a hosted card's resource URI to an endpoint on your server.

Hosted Card Transactions

A hosted card transaction can be started by setting doCreateTransaction to false when you create a payment session. Instead of creating a transaction for the payment session after capturing payment information from the shopper, Converge returns a hosted card resource URI to an endpoint you provide.

Hosted cards only remain valid for 30 minutes. If you use a hosted card more than 30 minutes after its creation, the transaction will fail.
3D Secure

A reason to consider disabling end to end transactions is if your business case needs different security checks than the default 3D Secure check Converge provides. The hosted card masks sensitive fields of information but provides the required fields to perform custom 3-D Secure validations.

Lightbox

When using the lightbox, you will need to set the form you use to initiate a lightbox checkout to post the information returned from a successful checkout to an endpoint that is prepared to handle the process.

<form method="POST" action="/%3Cyour-hosted-card-accepting-endpoint%3E">
<script
     src="https://<hpp-url>/client/index.js"
     class="converge-button"
     data-public-key="<your-public-key>"
     data-session-id="<your-payment-session-id>"
     data-merchant-alias="<your-merchant-alias>">
</script>
</form>

Redirect

With a Redirect, the information is returned as a query parameter sent to the URL you provide as the returnUrl property of the payment session.

{
   "order": "https://api.eu.convergepay.com/orders/p7hxrvrpgfc68w6gm7q3b47y",
    "returnUrl": "https://merchant.com/return",
    "cancelUrl": "https://merchant.com/cancel" 
}

A payment session created with a body holding the previous example would return the shopper to your website by placing a get request to the following URL:  https://merchant.com/return?token=<hosted-card-uri>

Create The Transaction

After receiving the hosted card resource URI and completing any additional steps you need to before processing the transaction, you will need to create a Transaction.

To create a transaction, POST to the /transactions endpoint. The body of the post must include the total and hostedCard properties. Use the returned URI as the value for hostedCard.

{
   "total": [
     {
       "amount": "6.00",
       "currencyCode": "EUR"
     },
     {
       "hostedCard": "https://api.eu.convergepay.com/hosted-cards/jqm7yjf83bydgytbpcmxbm49",
       "doCapture": "false"
     }
   ]
 }

Related Pages