Alma

Last updated: October 30, 2024

Alma offers a Pay Later solution that enables your customers to pay 15 or 30 days after their purchase.

Information

To enable Alma payments on your account, contact your Account Manager or [email protected].

Model	Gateway
Payment flow	Redirect
Payment method type	Buy now, pay later (BNPL)
One-step payment
Authorization
Capture
Refund
Partial refund
Chargeback
Recurring payment

To accept Alma payments, follow these steps:

To send a payment request, call the payments endpoint:

post

https://api.checkout.com/payments

If you don't provide a customer ID or email address in the request, Checkout.com automatically creates a customer profile and returns the customer ID in the response.


1{
2  "amount": 6001,
3  "currency": "EUR",
4  "source": {
5    "type": "alma",
6    "billing_address": {
7      "address_line1": "123 High St.",
8      "address_line2": "Flat 456",
9      "city": "London",
10      "zip": "SW1A 1AA",
11      "country": "GB"
12    }
13  },
14  "failure_url": "https://example.com/payments/failure",
15  "success_url": "https://example.com/payments/success",
16  "reference": "ORD-5023-4E89",
17  "customer": {
18    "name": "John Smith",
19    "email": "[email protected]",
20    "phone": {
21      "country_code": "+44",
22      "number": "1234 567890"
23    }
24  },
25  "shipping": {
26    "address": {
27      "address_line1": "123 High St.",
28      "address_line2": "Flat 456",
29      "city": "London",
30      "zip": "SW1A 1AA",
31      "country": "GB"
32    }
33  },
34  "capture": true
35}

If you receive a 202 Accepted response with a payment id value and the status field set to Pending, your request was successful.


1{
2  "id": "pay_uexsi2rik7ceppidytigjmxshi",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_rckdrxsk5j7efn7slcem7rofve",
7    "email": "[email protected]",
8    "name": "John Smith",
9    "phone": {
10      "number": "1234 567890",
11      "country_code": "+44"
12    }
13  },
14  "processing": {
15    "partner_payment_id": "payment_11uwPpq2eBVJV3QMphBQk2OIsUnkE1sKay"
16  },
17  "_links": {
18    "self": {
19      "href": "https://api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi"
20    },
21    "redirect": {
22      "href": "https://pay.staging.getalma.eu/11uwPpq2eBVJV3QMphBQk2OIsUnkE1sKay"
23    }
24  }
25}

Redirect the customer to the redirect link's href in the response. This redirect enables the customer to authorize the payment, before they are transferred to your predefined success or failure URL.

To retrieve details about the payment, call the payments endpoint, setting the payment_id value from the payment response as the {id} path parameter:

post

https://api.checkout.com/payments/{id}

See Get payment details for more information.


1{
2  "id": "pay_uexsi2rik7ceppidytigjmxshi",
3  "requested_on": "2022-07-11T08:59:44.7324985Z",
4  "source": {
5    "type": "alma"
6  },
7  "amount": 6001,
8  "currency": "EUR",
9  "payment_type": "Regular",
10  "reference": "ORD-5023-4E89",
11  "status": "Pending",
12  "customer": {
13    "id": "cus_rckdrxsk5j7efn7slcem7rofve",
14    "email": "[email protected]",
15    "name": "John Smith",
16    "phone": {
17      "country_code": "+44",
18      "number": "1234 567890"
19    }
20  },
21  "shipping": {
22    "address": {
23      "address_line1": "123 High St.",
24      "address_line2": "Flat 456",
25      "city": "London",
26      "zip": "SW1A 1AA",
27      "country": "GB"
28    }
29  },
30  "processing": {
31    "partner_payment_id": "payment_11uwPpq2eBVJV3QMphBQk2OIsUnkE1sKay"
32  },
33  "_links": {
34    "redirect": {
35      "href": "https://pay.staging.getalma.eu/11uwPek5EdoeqjdWXtgCUaqvSROlz7T2WD"
36    },
37    "self": {
38      "href": "https://api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi"
39    },
40    "actions": {
41      "href": "https://api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi/actions"
42    }
43  }
44}


1{
2  "id": "pay_uexsi2rik7ceppidytigjmxshi",
3  "requested_on": "2022-07-11T08:59:44.7324985Z",
4  "source": {
5    "type": "alma"
6  },
7  "amount": 6001,
8  "currency": "EUR",
9  "payment_type": "Regular",
10  "reference": "ORD-5023-4E89",
11  "status": "Captured",
12  "approved": true,
13  "balances": {
14    "total_authorized": 6001,
15    "total_voided": 0,
16    "available_to_void": 0,
17    "total_captured": 6001,
18    "available_to_capture": 0,
19    "total_refunded": 0,
20    "available_to_refund": 6001
21  },
22  "customer": {
23    "id": "cus_rckdrxsk5j7efn7slcem7rofve",
24    "email": "[email protected]",
25    "name": "John Smith",
26    "phone": {
27      "country_code": "+44",
28      "number": "1234 567890"
29    }
30  },
31  "shipping": {
32    "address": {
33      "address_line1": "123 High St.",
34      "address_line2": "Flat 456",
35      "city": "London",
36      "zip": "SW1A 1AA",
37      "country": "GB"
38    }
39  },
40  "processing": {
41    "partner_payment_id": "payment_11uwPpq2eBVJV3QMphBQk2OIsUnkE1sKay"
42  },
43  "_links": {
44    "self": {
45      "href": "https://api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi"
46    },
47    "actions": {
48      "href": "https://api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi/actions"
49    },
50    "refund": {
51      "href": "https://api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi/refunds"
52    }
53  }
54}

Alma supports both partial and full refunds.

You can refund the payment through the Dashboard or by calling the Refund a payment endpoint, setting the payment_id value from the payment response as the {id} path parameter.

post

https://api.checkout.com/payments/{id}/refunds

See Refund a payment for more information.


1{
2  "amount": 10
3}


1{
2  "action_id": "act_f544khcfnyqudh3l73qwnnvfbi",
3  "_links": {
4    "payment": {
5      "href": "https://api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi"
6    }
7  }
8}

Once you create a payment using the auto-capture payment flow, you cannot void it. If you want to reverse a payment that is in progress, wait until you receive the payment_captured webhook, and then process a refund.

If the customer cancels or fails to complete their payment, we send a payment_expired webhook.

When integrating with Alma, you can configure the following webhooks using our API, or the Dashboard:

Webhook	Description
`payment_pending`	Sent when a payment request has been successfully initiated.
`payment_expired`	Sent when a payment request has expired.
`payment_declined`	Sent when a payment request has been rejected.
`payment_captured`	Sent when the payment has been successfully captured.
`payment_refunded`	Sent when the payment has been (fully or partially) refunded.
`payment_refund_declined`	Sent when a refund has been declined.

Contact your Account Manager or [email protected] to enable Alma payments in your test environment. Checkout.com provides you with test values to send a payment request.

To test your integration:

Send a payment to the Sandbox environment, following the redirect link in the response to Alma's website.
Enter the name, test card details, and the test phone number provided.
Confirm the message code you received on the test phone number.
Select Submit.

You are then redirected to your predefined success URL.

Alma

Information

Request a payment

Request example

Response example

Redirect the customer

Get details about a payment

Response example

Refund a payment

Request example

Response example

Cancel a payment

Configure webhooks

Test your integration