Alma for Payment Setup API

Last updated: April 30, 2026

To accept Alma payments, you must:

Create a payment setup.
Confirm the payment.
Redirect the customer to Alma.

Checkout.com supports Alma payments in France only. The customer must be located in France (FR) to use Alma.

Call the Create a payment setup endpoint.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payments/setups


1{
2  "amount": 6001,
3  "currency": "EUR",
4  "billing": {
5    "address": {
6      "address_line1": "12 Rue de la Paix",
7      "city": "Paris",
8      "country": "FR"
9    }
10  },
11  "settings": {
12    "success_url": "https://example.com/payments/success",
13    "failure_url": "https://example.com/payments/failure"
14  },
15  "reference": "ORD-5023-4E89"
16}

In the request body, provide the following:

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`billing` object	The customer's billing details. Required
`billing.address` object	The customer's billing address. Required
`billing.address.address_line1` string	The first line of the billing address. Required
`billing.address.city` string	The city of the billing address. Required
`billing.address.country` string	The country of the billing address. Supported value: `FR` Required
`currency` string	Three-letter ISO 4217 currency code. Supported value: `EUR` Required
`settings.failure_url` string	The URL to redirect the customer to if the payment fails. Format: URI Max length: 1024 Required
`settings.success_url` string	The URL to redirect the customer to if the payment is successful. Format: URI Max length: 1024 Required
`description` string	A description of the payment. Max length: 100
`reference` string	A reference you can use to identify the payment. Max length: 80


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 6001,
5  "currency": "EUR",
6  "payment_type": "Regular",
7  "reference": "ORD-5023-4E89",
8  "description": "Alma payment",
9  "payment_methods": {
10    "alma": {
11      "status": "ready",
12      "flags": []
13    }
14  },
15  "available_payment_methods": [
16    "alma"
17  ],
18  "settings": {
19    "success_url": "https://example.com/payments/success",
20    "failure_url": "https://example.com/payments/failure"
21  }
22}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

When all required fields are present, the payment_methods.alma object shows a ready status.

Confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
alma as the payment method name.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/alma


1{
2  "id": "pay_uexsi2rik7ceppidytigjmxshi",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_rckdrxsk5j7efn7slcem7rofve",
7    "email": "hannah.bret@example.com",
8    "name": "Hannah Bret"
9  },
10  "processing": {
11    "partner_payment_id": "payment_11uwPpq2eBVJV3QMphBQk2OIsUnkE1sKay"
12  },
13  "_links": {
14    "self": {
15      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi"
16    },
17    "redirect": {
18      "href": "https://pay.staging.getalma.eu/11uwPpq2eBVJV3QMphBQk2OIsUnkE1sKay"
19    }
20  }
21}

Redirect the customer to the redirect.href URL from the response. The customer completes the payment on the Alma page and is then redirected back to your settings.success_url or settings.failure_url.

Alma for Payment Setup API

Create a payment setup

Information

Request example

Response example

Confirm the payment

Request example

Response example

Redirect the customer