# iDEAL for Unified Payments API

iDEAL payments follow this process:

1. [Request a payment](#Request_a_payment).
2. [Redirect the customer](#Redirect_the_customer).
3. [Consume webhook with the result of the payment](#Webhooks).
4. [Refund a payment](#Refund_a_payment).

---

## Request a payment

Use the following details to set up your request. For a detailed view of all required and optional fields, see the [API reference](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout).

### Endpoints

> **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`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "source": {
    "type": "ideal",
    "description": "ORD50234E89",
    "language": "nl"
  },
  "amount": 2000,
  "currency": "EUR",
  "reference": "iDEALabcde21",
  "success_url": "http://example.com/payments/success",
  "failure_url": "http://example.com/payments/fail"
}
```

> **Information**
>
> If a customer ID or email is not provided in the request, then we automatically create a customer profile and return the customer `id` in the response.

### Response example

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

```json
{
  "id": "pay_yndlioum4gau3oizxihvzdgp4i",
  "status": "Pending",
  "customer": {
    "id": "cus_xalxia5mzjau3fv5gkuylu3xla",
    "email": "test@example.com"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_oaflx2w5greulin5u4l3uwwyj4"
    },
    "redirect": {
      "href": "https://sandbox.ideal-acquiring.ing.nl/ideal/iDEALv3/issuer/simulation?transactionId=0051100036109376&random=1d2e57594bf6c948c84014856f869349ba131ba25cefe5cd57c99dd396f7a40c"
    }
  }
}
```

---

## Redirect the customer

Redirect your customer to the `redirect` link’s href in the Request a payment response.

The redirect transfers the customer to their bank's website where they are required to enter their authorization details. If the authorization is successful, the payment can be approved.

Ensure that you open the redirect URL in the same window where your customer selected iDEAL as the payment method.

> **Note**
>
> For security reasons, iDEAL forbids using custom-made in-app browsers for redirection. We recommend that you open the device’s default browser to display the redirect. If you do want to use an in-app web view, you must use [SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller) for iOS or [Chrome Custom Tabs](https://developer.chrome.com/multidevice/android/customtabs) for Android.

Once completed, the customer is transferred to your predefined success or failure URL. Confirmation of an iDEAL payment is communicated only through webhooks. When you receive a `payment_captured` webhook, the transaction has been completed successfully. Until the `payment_captured` webhook is received (response code `10000`), all payments are labeled as _Pending_.

---

## Get details about a payment

To retrieve details about the payment, you can use either the `id` found in the payment response or the `cko-session-id` from the success/failure URL. For example, `https://www.checkout.com/order/succeeded?cko-session-id=`. For details about all required and optional fields, see the [API reference](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentDetails).

> **Note**
>
> The `cko-session-id` expires 15 minutes after being created.

### Endpoints

> **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**

`GET` `https://{prefix}.api.checkout.com/payments/{id}`

**Sandbox**

`GET` `https://{prefix}.api.sandbox.checkout.com/payments/{id}`

### Response example

```json
{
  "id": "pay_gx2pyzir3nzuhfmz7djlrxuhre",
  "requested_on": "2024-03-01T09:21:08Z",
  "source": {
    "type": "ideal",
    "description": "iDEAL Demo Payment",
    "bic": "INGBNL2A",
    "iban": "NL53INGB0654422370",
    "account_holder_name": "Hr E G H Küppers en/of MW M.J. Küppers-Veeneman"
  },
  "amount": 100,
  "currency": "EUR",
  "payment_type": "Regular",
  "status": "Captured",
  "approved": true,
  "risk": {
    "flagged": false
  },
  "customer": {
    "id": "cus_smscm3h2nqpe3obmau4djsqfam"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_gx2pyzir3nzuhfmz7djlrxuhre"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_gx2pyzir3nzuhfmz7djlrxuhre/actions"
    },
    "refund": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_gx2pyzir3nzuhfmz7djlrxuhre/refunds"
    }
  }
}
```

---

## Cancel a payment

If the customer fails to complete their payment, we will automatically void the payment in 10 minutes and send a `payment_expired` webhook.

If the customer cancels their payment, we will send a `payment_canceled` webhook.

---

 Refund a payment

iDEAL supports both partial and full refunds. You can refund a payment through the [Dashboard](https://dashboard.checkout.com) or using the [Refund a payment](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment) endpoint.

---

## Testing iDEAL

> **Note**
>
> To start testing, you need to do the following:
>
> - [Create a test account](https://www.checkout.com/get-test-account).
> - Contact your account manager or integrations engineer to activate iDEAL payments in the sandbox environment.

### Test a payment request

1. Create an iDEAL transaction.
2. Browse to the redirect link in the transaction response.
3. In your browser, select the _TESTNL2A_ bank.
4. Select _Success_ when asked which test simulation you want to run.

You should now be redirected to your predefined success URL.

### Simulate payment states

After selecting the _TESTNL2A_ bank, you can select any payment state you want to test from the bank's UI.

> **Note**
>
> When you test a payment refund, the transaction is likely to remain in a deferred refund state. [Contact us](https://dashboard.checkout.com/support?topic=case_transactions) to request triggering a simulation batch job that ensures the completion of the refund.