Collect Payments by Card
Once a customer has been enrolled with a card alias, SlimPay allows merchants to collect one-off payments or set up recurring payment plans without needing to display the Checkout to the consumer. Card aliases can be used to process payments with a server-to-server call to the SlimPay API!
This step-by-step guide walks you through the process of collecting server-to-server card payments.
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.
To directly collect a one-off card payment, we make an API call using the create-payins relation, which can be found at the entry point. The table below lists all of the parameters that you need to create a card payment. 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 |
---|---|---|---|
creditor » reference | Alphanumeric | 35 | |
cardAlias » reference or subscriber » reference |
Alphanumeric | 35 | |
payment reference If null , SlimPay will generate a unique reference. |
Alphanumeric without special characters | 35 | |
amount | Decimal | 19 | |
currency
|
An ISO 4217 currency code | 3 | |
scheme
|
Alphanumeric | 35 | |
label | Alphanumeric | 140 | |
capture A true/fasle flag to indicate whether a card payment should be captured or not (by default set to true). |
Boolean | ||
executionDate As soon as possible if null .Cannot be set more than 7 days in advance (including the current day). |
A date, formatted to ISO 8601 standard E.g. 2021-11-03T00:00:00.000+0100 | 28 |
Below is an example of the create-payins API call using our PHP HTTP Client:
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#create-payins');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
'creditor' => [
'reference' => 'yourCreditorReference'
],
'cardAlias' => [
'reference' => 'theCardAliasReference'
],
'reference' => null,
'amount' => 29.99,
'currency' => 'EUR',
'scheme' => 'CARD',
'label' => 'January subscription fee',
'executionDate' => null
]
));
$payment = $hapiClient->sendFollow($follow);
In the example above, the card alias reference was used to create the payment. If a merchant provided the subscriber reference instead, SlimPay would use the most recently activated card alias associated with this subscriber.
When trying to create the payment, it can be synchronously rejected by our API if a parameter is missing or not formatted correctly.
Otherwise, the server responds with a 201 Created
HTTP status. The payment is created and returned in the response.
Below is an example of a created card payment:
{
"amount": "25.00",
"confirmed": false,
"currency": "EUR",
"dateCreated": "2021-07-03T15:44:10.641+0000",
"direction": "IN",
"executionDate": "2021-07-12T22:00:00.000+0000",
"executionStatus": "toprocess",
"id": "edbc7803-7ed7-11e8-bf72-000000000000",
"label": "The label",
"processor": "slimpay",
"reference": "Payment 123",
"scheme": "CARD",
"state": "accepted",
"_links": {
...
}
}
From the response example above, the following three properties are important to note:
id
: the payment ID generated by SlimPay. You’ll need to store this in order to retrieve the payment laterexecutionDate
: the date on which the amount is expected to be settled by the clearing house. This can be set by you, or it will be generated by SlimPay for the earliest possible dateexecutionStatus
: the payment starts astoprocess
, marking the beginning of its life cycle described below
Card authorization
The create-payins relation can also be used for card authorization, in order to confirm and hold an amount of funds on a cardholder’s account. After a period of 7 days, the amount will be deducted. The card authorization can be cancelled any time before the end of the 7-day period.
To perform a card authorization, set the capture
parameter in the create-payins API call to false.
Creating recurrent card payment plans
To create a payment plan of recurring card payments, we make an API call using the create-recurrent-card-transactions relation, which can be found at the entry point. The table below lists all of the parameters that you need to create a payment plan. 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 |
---|---|---|---|
creditor » reference | Alphanumeric | 35 | |
cardAlias » reference or subscriber » reference |
Alphanumeric | 35 | |
payment reference If null , SlimPay will generate a unique reference. |
Alphanumeric without special characters | 35 | |
amount | Decimal | 19 | |
currency
|
An ISO 4217 currency code | 3 | |
label | Alphanumeric | 140 | |
frequency The frequency of the direct debit transactions.
|
Alphanumeric | 16 | |
maxTxNumber The maximum number of recurrent card transactions that should be created with this payment plan. If not provided, the payment plan will have no limit until cancelled. |
Integer | 3 | |
dateFrom The date of the first card transaction. |
A date, formatted to ISO 8601 standard E.g. 2021-11-03T00:00:00.000+0100 | 28 |
Below is an example of the create-recurrent-direct-debits API call using our PHP HTTP Client:
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#create-recurrent-card-transactions');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
'creditor' => [
'reference' => 'yourCreditorReference'
],
'subscriber' => [
'reference' => 'theSubscriberReference'
],
'amount' => 100,
'currency' => 'EUR',
'frequency' => 'monthly',
'maxTxNumber' => '12',
'dateFrom' => '2021-07-12T22:00:00.000+0000',
'label' => 'Card payment plan'
]
));
$payment_plan = $hapiClient->sendFollow($follow);
The example above is for a payment plan of 12 monthly installments of €100 each. The payment plan will be created for the most recently activated card alias associated with the subscriber.
Collecting card payments by Dashboard
Card payments can also be processed using SlimPay’s Dashboard interface. For documentation on this process, please refer to our Help Center.
Modifying recurring card payments
Once a card payment plan has been created, merchants can cancel it by API or via the Dashboard.
The cancel-recurrent-card-transaction relation allows merchants to permanently discontinue the card payment plan.
Alternatively, cancellations to recurring card payment plans can be made via the Dashboard. For specific documentation, refer to our Help Center.
Determining whether a card payment was successful
SlimPay allows merchants to track the status of card payments to confirm whether they have been successfully processed.
To retrieve all card payments for a specific customer, you can use the search-payments relation available at the API entry point, providing your creditor reference, the payment scheme (CARD) and the subscriber reference as parameters. All card payments created for that specific debtor will be returned in a collection by the SlimPay server.
To retrieve the status of a specific payment, you can use the search-payment-by-id relation available at the API entry point, providing the ID of the card payment.
In the event that a card payment has failed, SlimPay has a range of mechanisms in place for retrieving and recovering payment issues. Further documentation on handling R-transactions can be found here.
The card payment refund timeline
Card payment refunds can be issued up to 12 months after the initial payment. Documentation on how to process card refunds can be found here.
Card Payment Life Cycle
Execution Status | Description |
---|---|
toprocess |
A card authorization request has been created by the merchant and validated by the card networks. |
processing |
The card capture was succesful. Funds will be received 1 or 2 days later. |
notprocessed |
Either the authorization has expired or the capture have been rejected, or they have been cancelled by the merchant. |
processed |
Funds received by SlimPay. |
rejected |
The capture was subject to a chargeback. |