Alma for API only

Last updated: March 19, 2025

To accept Alma payments, follow these steps:

To send a payment request, call the payments endpoint:

post

https://api.checkout.com/payments

If you do not 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": "john.smith@example.com",
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": "john.smith@example.com",
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": "john.smith@example.com",
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": "john.smith@example.com",
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.

To enable Alma payments in your sandbox environment, contact your account manager or request support. Checkout.com provides you with test values to send a payment request.

To test your integration:

Send a payment to the Sandbox environment, and open 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 for API only

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

Test your integration