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.

For more information, see the Hosted Cards resource and the Payment Sessions resource.

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

To create a transaction, send a Create Transaction POST request to the /transactions endpoint. The body of the post only requires the payment session's resource URL. This is obtained from a successful Create PaymentSession response.

Below is an example on how to create a transaction from the UAT environment:

POST "https://uat.api.converge.eu.elavonaws.com/transactions"
{
    "paymentSession": "https://uat.api.converge.eu.elavonaws.com/payment-sessions/rd8y9xhx7qh9yj6r4vpxpqcv"
}

For more information, see the Transactions resource and the Payment Sessions resource.