# Alma for Unified Payments API To accept Alma payments, follow these steps: 1. [Request a payment](#Request_a_payment). 2. [Redirect the customer](#Redirect_the_customer). --- ## Request a payment To send a payment request, call the [payments](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint: **Live** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` ### Request example 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. ```json { "amount": 6001, "currency": "EUR", "source": { "type": "alma", "billing_address": { "address_line1": "123 High St.", "address_line2": "Flat 456", "city": "London", "zip": "SW1A 1AA", "country": "GB" } }, "failure_url": "https://example.com/payments/failure", "success_url": "https://example.com/payments/success", "reference": "ORD-5023-4E89", "customer": { "name": "John Smith", "email": "john.smith@example.com", "phone": { "country_code": "+44", "number": "1234 567890" } }, "shipping": { "address": { "address_line1": "123 High St.", "address_line2": "Flat 456", "city": "London", "zip": "SW1A 1AA", "country": "GB" } }, "capture": true } ``` ### Response example If you receive a `202 Accepted` response with a payment `id` value and the `status` field set to `Pending`, your request was successful. ```json { "id": "pay_uexsi2rik7ceppidytigjmxshi", "status": "Pending", "reference": "ORD-5023-4E89", "customer": { "id": "cus_rckdrxsk5j7efn7slcem7rofve", "email": "john.smith@example.com", "name": "John Smith", "phone": { "number": "1234 567890", "country_code": "+44" } }, "processing": { "partner_payment_id": "payment_11uwPpq2eBVJV3QMphBQk2OIsUnkE1sKay" }, "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi" }, "redirect": { "href": "https://pay.staging.getalma.eu/11uwPpq2eBVJV3QMphBQk2OIsUnkE1sKay" } } } ``` --- ## Redirect the customer 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. --- ## Get details about a payment To retrieve details about the payment, call the [payments](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentsList) endpoint, setting the `payment_id` value from the payment response as the `{id}` path parameter: **Live** `POST` `https://{prefix}.api.checkout.com/payments/{id}` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}` See [Get payment details](https://www.checkout.com/docs/payments/manage-payments/get-payment-details) for more information. ### Response example **Pending** ```json withBorder={false} { "id": "pay_uexsi2rik7ceppidytigjmxshi", "requested_on": "2022-07-11T08:59:44.7324985Z", "source": { "type": "alma" }, "amount": 6001, "currency": "EUR", "payment_type": "Regular", "reference": "ORD-5023-4E89", "status": "Pending", "customer": { "id": "cus_rckdrxsk5j7efn7slcem7rofve", "email": "john.smith@example.com", "name": "John Smith", "phone": { "country_code": "+44", "number": "1234 567890" } }, "shipping": { "address": { "address_line1": "123 High St.", "address_line2": "Flat 456", "city": "London", "zip": "SW1A 1AA", "country": "GB" } }, "processing": { "partner_payment_id": "payment_11uwPpq2eBVJV3QMphBQk2OIsUnkE1sKay" }, "_links": { "redirect": { "href": "https://pay.staging.getalma.eu/11uwPek5EdoeqjdWXtgCUaqvSROlz7T2WD" }, "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi" }, "actions": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi/actions" } } } ``` **Captured** ```json withBorder={false} { "id": "pay_uexsi2rik7ceppidytigjmxshi", "requested_on": "2022-07-11T08:59:44.7324985Z", "source": { "type": "alma" }, "amount": 6001, "currency": "EUR", "payment_type": "Regular", "reference": "ORD-5023-4E89", "status": "Captured", "approved": true, "balances": { "total_authorized": 6001, "total_voided": 0, "available_to_void": 0, "total_captured": 6001, "available_to_capture": 0, "total_refunded": 0, "available_to_refund": 6001 }, "customer": { "id": "cus_rckdrxsk5j7efn7slcem7rofve", "email": "john.smith@example.com", "name": "John Smith", "phone": { "country_code": "+44", "number": "1234 567890" } }, "shipping": { "address": { "address_line1": "123 High St.", "address_line2": "Flat 456", "city": "London", "zip": "SW1A 1AA", "country": "GB" } }, "processing": { "partner_payment_id": "payment_11uwPpq2eBVJV3QMphBQk2OIsUnkE1sKay" }, "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi" }, "actions": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi/actions" }, "refund": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi/refunds" } } } ``` --- ## Refund a payment Alma supports both partial and full refunds. You can refund the payment through the [Dashboard](https://dashboard.checkout.com) or by calling the [Refund a payment](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment) endpoint, setting the `payment_id` value from the payment response as the `{id}` path parameter. > **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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payments/{id}/refunds` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}/refunds` See [Refund a payment](https://www.checkout.com/docs/payments/manage-payments/refund-a-payment) for more information. ### Request example ```json { "amount": 10 } ``` ### Response example ```json { "action_id": "act_f544khcfnyqudh3l73qwnnvfbi", "_links": { "payment": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi" } } } ``` --- ## Cancel a payment 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. --- ## Test your integration To enable Alma payments in your sandbox environment, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). Checkout.com provides you with test values to send a payment request. To test your integration: 1. Send a payment to the Sandbox environment, and open the redirect link in the response to Alma's website. 2. Enter the name, test card details, and the test phone number provided. 3. Confirm the message code you received on the test phone number. 4. Select _Submit_. You are then redirected to your predefined success URL.