Worldline Account-to-Account Payments

• Overview
• Countries & currencies
• Integration
• Process flows
• Testing
• Additional information
• Consumer experience
• Reporting
• FAQ

Integration

• Using MyCheckout hosted payment pages
• Using your own checkout page
• Customer redirection
• Showing target and source currencies
• Refund
• Webhooks

Before you begin

To follow along with this guide, please ensure that you have the following ready:

• The correct API endpoint
• A way to construct the authorization header (API Explorer, SDKs, etc.)
• A way to send REST API calls (API Explorer, SDKs, etc.)

Using MyCheckout hosted payment pages

1. Make a POST /v1/{merchantId}/hostedcheckouts API call.
2. Create the order object containing the following properties:

• amountOfMoney, including amount and currencyCode
• customer, including merchantCustomerId, billingAddress including countryCode 

Additionally, you can add hostedCheckoutSpecificInput object, featuring variant and locale properties:

• variant - the created styling of the checkout page tailored to your consumer's preferences
• locale - the language, that will be used for your hosted checkout page

The below example allows the consumer to select a payment product on our hosted payment page and be redirected to the next page, where they select the option with which they want to pay.

{
    "order": {
        "amountOfMoney": {
            "currencyCode": "GBP",
            "amount": "10000"
        },
        "customer": {
            "merchantCustomerId": 89769876,
            "billingAddress": {
                "countryCode": "GB"
            }
        }
    },
    "hostedCheckoutSpecificInput": {
        "locale": "en_GB",
        "variant": "105"
    }
}

{
    "RETURNMAC": "959535b0-c1a1-4f5f-865e-d55776367c69",
    "hostedCheckoutId": "065d3625-ed4f-71ff-9de6-6bf8c2c79ebf",
    "partialRedirectUrl": "pay2.preprod.checkout.worldline-solutions.com/checkout/88005-7f4cdb166ccb4712930c6df0028d4283:065d3625-ed4f-71ff-9de6-6bf8c2c79ebf:bb9b2eee735c43aab6db5513ee170983"
}

From the response, the important properties are:

• hostedCheckoutId – can be used in subsequent API calls to retrieve the transaction details, such as GET/v1/{merchantId}/hostedcheckouts/{hostedCheckoutId}
• partialRedirectUrl – is used to create the URL to which the customer needs to be redirected. By default, we configure every account with the subdomain payment, so you can always connect https://payment. with the partialRedirectUrl, for example:

https://pay2.preprod.checkout.worldline-solutions.com/checkout/88005-7f4cdb166ccb4712930c6df0028d4283:065d3625-ed4f-71ff-9de6-6bf8c2c79ebf:bb9b2eee735c43aab6db5513ee170980

For more information on customizing the MyCheckout hosted payment pages, please refer to our detailed guide.

Using your own checkout page

You can build a direct integration using our SDKs (or integrate our API from scratch). Depending on your integration needs, there are several options available.

Client encryption

Our Client API allows you to perform various actions. All you need is to be able to create a session via the POST/v1/{merchantId}/sessions API call, which will grant you access to the Client API. It's highly recommended that you use our Client SDKs.

We also have reference implementations showing how to use these SDKs on GitHub

Non-encrypted data

If you wish to do a direct server-to-server API call, go for this option. The difference with the other options mentioned before is that you don't need to submit the encryptedCustomerInput property. After the consumer selects the payment product, you need to perform the following:

1. Make a POST /v1/{merchantId}/payments API call.
2. Create the order object containing the following properties:

• amountOfMoney, including amount and currencyCode
• customer, including merchantCustomerId, billingAddress including countryCode

1. Create redirectPaymentMethodSpecificInput object containing the following properties:

• paymentProductId
• redirectionData
• returnUrl

    {
    "order": {
        "amountOfMoney": {
            "currencyCode": "GBP",
            "amount": "123"
        },
        "customer": {
            "merchantCustomerId": 89769876,
            "billingAddress": {
                "countryCode": "GB"
            }
        }
    },
    "redirectPaymentMethodSpecificInput": {
        "paymentProductId": "865",
        "redirectionData": {
            "returnUrl": "http://example.com"
        }
    }
}

Customer redirection

If you use POST /v1/{merchantId}/payments API call, you also need to take care of the customer redirection (in the case of POST /v1/{merchantId}/hostedcheckouts, we handle it ourselves). We'll return a merchantAction object. While there are several different actionType values, for Worldline Account-to-Account Payments transactions, we consistently return the actionType value as REDIRECT.

Along with this, a redirectData object is included, containing a redirectURL. You'll need to direct your consumer to this URL to complete their payment.

Be aware that the merchantAction is only returned in the response to POST /v1/{merchantId}/payments and looks like this:

   {
    "creationOutput": {
        "additionalReference": "00000099911009937884",
        "externalReference": "000000999110099378840000100001"
    },
    "merchantAction": {
        "actionType": "REDIRECT",
        "redirectData": {
            "RETURNMAC": "b767441d-eb4b-42cb-b095-647585d1bbd1",
            "redirectURL": "https://checkout.sandbox.volt.io/nl/ZWUwZjBjNjYtM2VhMC00N2MwLThkMTMtNjgxODQxMWI4MzZl"
        },
        "showData": []
    },
    "payment": {
        "id": "000000999110099378840000100001",
        "paymentOutput": {
            "amountOfMoney": {
                "amount": 123,
                "currencyCode": "GBP"
            },
            "references": {
                "paymentReference": "999111453849"
            },
            "paymentMethod": "redirect",
            "redirectPaymentMethodSpecificOutput": {
                "paymentProductId": 865
            }
        },
        "status": "REDIRECTED",
        "statusOutput": {
            "isCancellable": false,
            "isRetriable": false,
            "statusCategory": "PENDING_PAYMENT",
            "statusCode": 50,
            "statusCodeChangeDateTime": "20240219152438",
            "isAuthorized": false,
            "isRefundable": false
        }
    }
}

The merchantAction is omitted from the GET /v1/{merchantId}/payments/{paymentId} API call and will return a response like this:

    {
    "id": "000008800510000124770000100001",
    "paymentOutput": {
        "amountOfMoney": {
            "amount": 123,
            "currencyCode": "GBP"
        },
        "references": {
            "paymentReference": "T8850004GC1A"
        },
        "paymentMethod": "redirect",
        "redirectPaymentMethodSpecificOutput": {
            "paymentProductId": 865
        }
    },
    "status": "REDIRECTED",
    "statusOutput": {
        "isCancellable": false,
        "isRetriable": false,
        "statusCategory": "PENDING_PAYMENT",
        "statusCode": 50,
        "statusCodeChangeDateTime": "20231222150036",
        "isAuthorized": false,
        "isRefundable": false
    }
}

Showing target and source currencies

The descriptor field displays currency conversions for payments made with Worldline Account-to-Account Payments. You can use it to show information on target and source currencies, including exchange rates.

Using the descriptor when making a payment request won't convert one currency to another. It's just there to provide information about the payment.

The descriptor should be sent in a specific format, including three elements separated by hashtags (#):

• Amount you want to pay in the targeted currency (without any decimal points)
• Target currency in ISO 4217 currency code
• Exchange rate between your source currency and the target currency, given with two decimal points

For example, the descriptor might look like this: 394#SGD#1.64

Assume you want to process payment in 2.40 pounds sterling (GBP) at an exchange rate of 1 GBP=1.64 Singapore dollars (SGD). Then it's expected you to calculate 3.94 SGD amount and pass these values by separating with the # symbol in the descriptor as follows:

{
   "order": {
       "amountOfMoney": {
           "currencyCode": "GBP",
           "amount": "240"
       },
       "customer": {
           "billingAddress": {
               "countryCode": "GB"
           },
           "contactDetails": {
               "emailAddress": "test@test.com"
           },
           "merchantCustomerId": "10001"
       },
       "references": {
           "descriptor": "394#SGD#1.64"
       }
   },
   "redirectPaymentMethodSpecificInput": {
       "paymentProductId": "865",
       "redirectionData": {
           "returnUrl": "https://www.example.com"
       }
   }
 }

Refund

To start a refund process, you should use the API call POST /v1/{merchantId}/payments/{paymentId}/refund. This action is only applicable if the payment status is PAID. If you wish to refund the full order amount, you can do so by sending a request using the same API call, but with an empty body. 

A basic refund payload only requires the amountOfMoney object specifying the amount and currencyCode:

    {
    "amountOfMoney": {
        "amount": 500,
        "currencyCode": "GBP"
    }
}

You have the option to refund a part of the funds as well. For this, it's necessary to include a payload with the amountOfMoney object, where you specify the amount and the currencyCode. Additionally, if you want to view the details of your refund, you can use the API call GET /v1/{merchantId}/refunds/{refundId}.

Webhooks

To track transaction status updates, you can subscribe to the following webhooks notifications:

• payment.created
• payment.redirected
• payment.pending_payment
• payment.captured
• payment.paid