# seQura for Unified Payments API

seQura has a two-step process:

1. [Request a payment](#Request_a_payment).
2. [Redirect the customer](#Redirect_the_customer).

---

## Payment options

seQura offers multiple payment options, which vary based on:

- The number of installments
- The period of time over which you want your customers to pay

You can specify the payment option in the payment request's `processing.product_type` field:

| Payment option | Description | product_type value |
| --- | --- | --- |
| Pay Later: Invoice | The customer pays seven days after the order is shipped. | `invoice` |
| Pay Later: (PP5) | The customer is redirected to a seQura page, where they can select the exact date they will pay for the order in full.<br><br>They can select any date between 30 to 45 days after shipping. | `pay_later` |
| Pay Later: Campaign Invoice | Seasonal campaigns function in a similar way to the Pay Later: Invoice payment option.<br><br>The difference is that you must specify the product (PP5) and campaign when you [fetch the identification form](https://docs.sequrapi.com/checkout/order_fetch_identification_form.html). | `pay_later` |
| Pay in 3 (SP1) | The customer pays for the order in three installments, with no additional interest applied. | `pay_by_instalment_3` |
| Pay in installment (PP3) | The customer is redirected to a seQura page, where they can select the number of monthly installments over which they'll pay for the order.<br><br>They can select any range between 3 and 24 monthly installments.<br><br>If the customer chooses to pay in 4 or more installments, a small interest fee is applied. | `pay_by_instalment` |
| Flexi | The Flexi option functions in a similar way to the Pay in installment payment option.<br><br>The difference is that the maximum number of monthly installments is determined by the contract you hold with seQura.<br><br>This payment option allows you to offer the Pay in 3 and other monthly installment options within the same widget. | `pay_by_instalment` |

You can offer your customers any number of these payment options on the checkout page.

Each option must be provided as a separate checkout button linked to a unique payment request with its own `processing.product_type` value.

---

## Request a payment

For the full API specification, see the [API reference](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout).

> **Information**
>
> If you're shipping a physical item as part of the customer order, you must set the corresponding item's `item[n].type` value to `physical` in the payment request.

**Live**

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

**Sandbox**

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

### Request example

```json
{
  "amount": 20000,
  "currency": "EUR",
  "source": {
    "type": "sequra",
    "billing_address": {
      "address_line1": "Carrer d'Alí Bei, 7",
      "city": "Madrid",
      "state": "Madrid",
      "zip": "08010",
      "country": "ES"
    }
  },
  "failure_url": "https://example.com/payments/failure",
  "success_url": "https://example.com/payments/success",
  "payment_ip": "203.0.113.0",
  "reference": "ORD-123XYZ",
  "customer": {
    "name": "Ali Farid",
    "email": "ali.farid@example.com"
  },
  "shipping": {
    "address": {
      "address_line1": "Carrer d'Alí Bei, 7",
      "city": "Madrid",
      "state": "Madrid",
      "zip": "08010",
      "country": "ES"
    }
  },
  "capture": true,
  "processing": {
    "product_type": "pay_later"
  },
  "items": [
    {
      "name": "Leadership training",
      "quantity": 1,
      "unit_price": 10000,
      "total_amount": 10000,
      "reference": "12368f7000111",
      "type": "digital",
      "service_ends_on":"2024-12-31"
    },
    {
      "name": "AI crash course",
      "quantity": 1,
      "unit_price": 10000,
      "total_amount": 10000,
      "reference": "12368f7000111",
      "type": "digital",
      "service_ends_on":"2024-12-31"
    }
  ]
}
```

### Response example

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

```json
{
  "id": "pay_bgmwsoadqdvetnljwg23hetl7q",
  "status": "Pending",
  "reference": "ORD-123XYZ",
  "customer": {
    "id": "cus_ujs5uvwcshhujllodxegkknwou",
    "email": "ali.farid@example.com",
    "name": "Ali Farid"
  },
  "processing": {
    "partner_payment_id": "a62d7832-543b-48c3-92c9-959160c09f5b",
    "product_type": "pay_later"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_bgmwsoadqdvetnljwg23hetl7q"
    },
    "redirect": {
      "href": "https://partner-integration-middleware-sandbox.sequra.com/checkout/a62d7832-543b-48c3-92c9-959160c09f5b"
    }
  }
}
```

---

## Redirect the customer

Redirect your customer to the URL in the response's `_links.redirect.href` field. This will allow the customer to authorize the payment, before they are transferred to your predefined success or failure URL.

---

## Apply a discount

To apply a discount to a specific item, specify an amount in the request's `items[].discount_amount` field.

To apply a discount to an entire order, specify an amount in the request's `processing.discount_amount` field. This amount must include the total of all `items[].discount_amount` values, as well as any discounts applied to the entire order.

You can apply discounts when you:

- Request a payment.
- Capture a payment.
- Refund a payment.

---

## Get details about a payment

You can retrieve details about an existing seQura payment with the following endpoint.

For the full API specification, see the [API reference](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentsList).

**Live**

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

**Sandbox**

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

### Response example

```json
{
  "id": "pay_bgmwsoadqdvetnljwg23hetl7q",
  "requested_on": "2024-01-09T11:37:17.6628468Z",
  "source": {
    "type": "sequra"
  },
  "items": [
    {
      "name": "Leadership training",
      "quantity": 1,
      "unit_price": 10000,
      "reference": "12368f7000111",
      "total_amount": 10000,
      "type": "digital",
      "service_ends_on": "2024-12-31"
    },
    {
      "name": "AI crash course",
      "quantity": 1,
      "unit_price": 10000,
      "reference": "12368f7000111",
      "total_amount": 10000,
      "type": "digital",
      "service_ends_on": "2024-12-31"
    }
  ],
  "amount": 20000,
  "currency": "EUR",
  "payment_type": "Regular",
  "reference": "ORD-123XYZ",
  "status": "Pending",
  "customer": {
    "id": "cus_ujs5uvwcshhujllodxegkknwou",
    "email": "ali.farid@example.com",
    "name": "Ali Farid"
  },
  "shipping": {
    "address": {
      "address_line1": "Carrer d'Alí Bei, 7",
      "city": "Madrid",
      "state": "Madrid",
      "zip": "08010",
      "country": "ES"
    }
  },
  "payment_ip": "203.0.113.0",
  "processing": {
    "partner_payment_id": "a62d7832-543b-48c3-92c9-959160c09f5b",
    "product_type": "pay_later"
  },
  "_links": {
    "redirect": {
      "href": "https://partner-integration-middleware-sandbox.sequra.com/checkout/a62d7832-543b-48c3-92c9-959160c09f5b"
    },
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_bgmwsoadqdvetnljwg23hetl7q"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_bgmwsoadqdvetnljwg23hetl7q/actions"
    }
  }
}
```

---

## Capture a payment

If you set `capture` to `true` in your payment request, we'll automatically authorize and capture the payment.

If you set `capture` to `false` in your payment request, we'll only authorize the payment. You'll need to manually capture the payment once you've shipped the items.

To perform a partial capture, include the `amount` and `items` objects when you perform your capture request.

**Live**

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

**Sandbox**

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

### Request example

```json
{
  "amount": 10000,
  "capture_type": "nonFinal",
  "reference": "CAPT-123-93833",
  "items": [
    {
      "name": "Leadership training",
      "quantity": 1,
      "unit_price": 10000,
      "reference": "12368f7000111",
      "total_amount": 10000,
      "type": "digital",
      "service_ends_on": "2024-12-31"
    }
  ]
}
```

### Response example

```json
 {
  "action_id": "act_6zg4ptgrpvzufmbkxwo2a4v2em",
  "reference": "CAPT-123-93833",
  "_links": {
    "payment": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_fw4vjk2zb6wezlo4hdsyurp2si"
    }
  }
}
```

---

## Refund a payment

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

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

### Request example

```json
{
  "amount": 10000,
  "items": [
    {
      "name": "Leadership training",
      "quantity": 1,
      "unit_price": 10000,
      "total_amount": 10000,
      "reference": "12368f7000111",
      "type": "digital",
      "service_ends_on":"2024-12-31"
    }
  ]
}
```

### Response example

```json
{
  "action_id": "act_alnfyh7afaoevhipr7ce7wxf4m",
  "_links": {
    "payment": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_fw4vjk2zb6wezlo4hdsyurp2si"
    }
  }
}
```

---

## Cancel a payment

Once a payment is created, you cannot void it. To void a payment in progress, wait for the `payment_captured` webhook, and then process a refund instead.

Communicating this to your end customer in advance may help you to avoid chargebacks.

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

---

## Perform a test payment

To start testing, contact your account manager or implementation engineer to activate seQura payments in the sandbox environment.

1. Request a seQura payment using the example. You can request to auto-capture or manually capture the payment.
2. Open the URL returned in the response's `_links.redirect.href` field in your browser. This will take you to the seQura website to authorize the payment.
3. Fill in the form fields with the following details:
    - _Fecha de nacimiento_ (date of birth) – Any valid date signifying that the customer is at least 18 years old
    - _DNI/NIE_ (personal identification number) – _66706324E_
    - _Teléfono móvil_ (phone number) – _+34 666 666 666_

4. Accept the terms of usage and select _Siguiente_ to continue to the next payment step.
5. In the security form that asks for the last five digits of the phone number, enter 66666.
6. When prompted for payment details, enter the following card information:
    - Card number – _4716773077339777_
    - Expiry – _12/30_
    - CVV – _123_

7. In the 3D Secure authentication form, enter _Checkout1!_ to authenticate the payment.

If the test payment was successful, you'll be redirected to the success URL you specified in the payment request.