Enrolling a customer for card payments
SlimPay’s Checkout solution offers merchants a frictionless and intuitive payment experience for their customers. Clients can be enrolled through a seamless payment journey, where credit card details can be obtained and payments can be collected in a single transaction.
This step-by-step guide will show you how to enroll a customer for card payments by creating a card alias using our Checkout solution. This involves creating the Checkout transaction, displaying the Checkout to the customer and informing you as the merchant when the transaction is completed.
Please note
This guide does not cover the basics of API authentication or the format of requests and responses. Please review these sections if you are unfamiliar with these concepts.
All of the code examples in our guides are written in PHP and are based on our HAPI Client, developed by SlimPay to reduce the code complexity of interfacing with our API. Please refer to our HTTP client page for more details on using these libraries.
The card payment flow is illustrated below:
Step 1: Create the Checkout transaction
Please note: card features are available for UAT and live accounts only and must be activated by SlimPay.
To enroll a customer for card payments, you will need to have at a minimum:
- your creditor reference
- the reference of your subscriber
- the payment scheme (Card)
The table below lists all of the parameters that you need to enroll a customer for card payments. Be sure to include all the properties that are mandatory, as well as any optional ones you wish.
All of the data you provide must conform to the constraints outlined in our comprehensive API reference.
Parameter | Mandatory | Format | Max length |
---|---|---|---|
locale One of de , en , es , fr , it , nl , pl , pt or null if you want to let SlimPay try to deduce it from the user's browser configuration. |
An ISO 639-1 standard country code (E.g. fr for France) | 2 | |
creditor » reference | Alphanumeric | 35 | |
subscriber » reference | Alphanumeric | 35 | |
paymentScheme
|
Alphanumeric | 35 |
With these parameters, you create the Checkout transaction through the create-orders relation available at the API entry point, using the orders and order items (of type cardAlias) resources. Below is an example of the create-orders API call using our PHP HTTP Client:
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#create-orders');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
'started' => true,
'locale' => 'fr',
'paymentScheme' => 'CARD',
'creditor' => [
'reference' => 'yourCreditorReference'
],
'subscriber' => [
'reference' => 'theSubscriberReference'
],
'items' => [
[
'type' => 'cardAlias'
]
]
]
));
$order = $hapiClient->sendFollow($follow);
$orderReference = $order->getState()['reference'];
The order returned by the SlimPay server should look something like this:
{
"id": "e9835ab8-01b9-11ec-a6ce-000000000000",
"reference": "e9835ab8-01b9-11ec-a6ce-000000000000",
"state": "open.running",
"locale": "fr",
"started": true,
"sendUserApproval": false,
"dateCreated": "2021-08-20T08:46:26.839+0000",
"dateStarted": "2021-08-20T08:46:26.839+0000",
"paymentScheme": "CARD",
"checkoutActor": "end_user"
}
Take note of the order reference (e9835ab8-01b9-11ec-a6ce-000000000000
) in both code examples above (a property which can optionally be chosen by the merchant during the create-orders API call). This reference needs to be stored in a variable because it will be used later to retrieve the order. Where this reference gets stored depends on how your application keeps track of its users (cookies, database, etc)... this is entirely up to you!
If your transaction flow doesn't rely on keeping a live session of your user’s payment journey, we can activate, as a last resort, an option which will add the order reference to the URL the user returns to when they are finished with the Checkout. This option does come with certain risks, so be careful about how you use it. To activate this option, please submit a request to our Customer Success team.
Step 2: Display the Checkout to the user
At this stage, the customer is directed to the SlimPay Checkout where they will provide their card details and approve its use for recurring payments:
$url = $order->getLink('https://api.slimpay.net/alps#user-approval')->getHref();
header('Location: ' . $url);
exit;
An alternative to redirecting the customer to a URL is to embed an iframe into your own application or website, or use an iframe popin to display the Checkout to the user. SlimPay’s HAPI Client can take care of the implementation of this, all you need to do is decode the HTML using base 64.
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#extended-user-approval');
$follow = new Http\Follow($rel, 'GET', [
'mode' => 'iframepopin' // Or iframeembedded
]);
$htmlCode = $hapiClient->sendFollow($follow, $order)->getState()['content'];
echo base64_decode($htmlCode);
The iframe popin will adapt to the size of the window, while an embedded iframe will take the size (width and height) of the parent container with a minimum of 320 pixels in height.
A further option is to send a link directing the customer to the SlimPay Checkout in a fully-customisable email. This link is valid for a period of 60 days, during which time a customer can click on the link up to five times to complete the Checkout process. Each time the customer clicks on the link, the Checkout session is active for 30 minutes.
At this stage, it is now up to the customer to complete or cancel the Checkout process.
Step 3: Be informed about the Checkout status
When a customer completes or cancels a Checkout transaction, a POST request is sent to your notification URL (if you provided one when configuring your app).
To retrieve the order in the notification URL, we need to decode the message body as a JSON object:
$body = file_get_contents('php://input');
$order = \HapiClient\Hal\Resource::fromJson($body);
Immediately after this synchronous notification ends, the customer can click on the continue button of the Checkout, which redirects them to the return URL (if you provided one when configuring your app).
To retrieve the order in the return URL, we must follow the get-orders relation using the order reference that was stored at the end of the first step:
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#get-orders');
$follow = new Http\Follow($rel, 'GET', [
'creditorReference' => 'yourCreditorReference',
'reference' => 'theOrderReference'
]);
$order = $hapiClient->sendFollow($follow);
An alternative to configuring a returnURL is to configure a number of dynamic URLs for handling specific use cases. These include:
- a failureUrl, which is a web page a customer is redirected to following an order failure during Checkout
- a successUrl, which is a web page a customer is redirected to following a successful order during Checkout
- a cancelUrl, which is a web page a customer is redirected to following a cancelled order during Checkout
Further documentation on URL management can be found on the SlimPay Help Center.
Once we’ve retrieved the customer’s order (whether it was cancelled or completed), let’s check its state
to trigger the appropriate action:
if (strpos($order->getState()['state'], 'closed.aborted') === 0) {
// The user did not complete the Checkout
// ... trigger some action(s) depending on your need
header('Location: failure-page.php');
exit;
} elseif (strpos($order->getState()['state'], 'closed.completed') === 0) {
// The user completed the Checkout successfully
// The card alias reference (needed to create payments)
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#get-card-alias');
$follow = new Http\Follow($rel);
$cardAlias = $hapiClient->sendFollow($follow, $order);
$cardAliasReference = $cardAlias->getState()['reference'];
// The subscriber reference that you provided
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#get-subscriber');
$follow = new Http\Follow($rel);
$subscriber = $hapiClient->sendFollow($follow, $order);
$subscriberReference = $subscriber->getState()['reference'];
// ... trigger some action(s) depending on your need
header('Location: success-page.php');
exit;
} else {
throw new Exception('Checkout is still open. State expected to be "closed".');
}
The example code above includes some suggestions for follow-up requests based on a successful transaction (like retrieving the card alias reference, which you’ll need to store in order to create payments).
The most common order states include:
closed.complete
: the customer has completed a successful orderclosed.aborted.aborted_byclient
: the customer has abandoned the orderclosed.aborted.aborted_byserver
: the order was cancelled by the server
Card By Link
SlimPay has a feature that allows merchants to email a link to their customers, where they can register a card for payments. By following this link, customers will be directed to the Checkout in order to provide their card details according to the process described above.
To make use of this feature via API, simply include the sendUserApproval property in the order resource, setting its value to true.
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#create-orders');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
'started' => true,
'locale' => 'fr',
'paymentScheme' => 'CARD',
'sendUserApproval' => true,
'creditor' => [
'reference' => 'yourCreditorReference'
],
'subscriber' => [
'reference' => 'theSubscriberReference'
],
'items' => [
[
// Your already existing order item of type cardAlias
// As defined in the Setting Up Card Payments guide
]
]
]
Remember to include the customer’s email address in the signatory object where the Checkout link will be sent.
Card by link payments can also be processed using the Dashboard. Further documentation regarding card by link via the Dashboard can be found on our Help Center.
Retrieving a card alias
Once a card alias has been created, SlimPay allows merchants to retrieve it either by API or through the Dashboard. Via the API, you can follow the get-order relation available at the entry point, providing your creditor reference and the order reference as parameters. Then simply follow the get-card-alias relation that is returned by the server. You can also follow the search-subscribers relation available at the entry point, providing your creditor reference and the subscriber reference as parameters. Then you can follow the get-card-alias relation associated with the subscriber.
Alternatively, you can follow the get-card-aliases relation available at the entry point, providing the card alias ID as a parameter.
Lastly, you can also retrieve the card alias by following the search-card-aliases relation available at the entry point, providing your creditor reference and subscriber reference as parameters.
Documentation on retrieving card aliases through the Dashboard can be found on our Help Center.
Testing your integration
In order to test your implementation in our preprod environment, SlimPay has a range of test data available, such as test IBANs and card numbers. Specific documentation regarding this test data can be found on the SlimPay Dev Center and Help Center.
Please note: Do no use real data (IBAN, phone number, address etc) during your preprod tests. However, any email addresses provided and used in our preprod environment must be valid, meaning you cannot use false or artificial email addresses in your tests.