# Integration Guide

## Overview

Alternative Payment Methods (further referred to as APMs) are similar to normal checkouts. One key difference is that the customer needs to take an additional action in order to finalize the payment with most APMs. Before proceeding, read the [online payments guide](/online-payments/).

## Check Available APMs

Check which payment methods are available to your merchant account.

1. [Create a checkout](/api/checkouts/create) and use the checkout `id` to fetch the list of available payment methods from the following endpoint `https://api.sumup.com/v0.1/checkouts/{checkout_id}/payment-methods`.

    Example response:

    ```json
    {
      "items": [
        {
          "id": "card",
          "name": "Credit Card"
        },
        {
          "id": "blik",
          "name": "Blik"
        },
        {
          "id": "apple_pay",
          "name": "Apple Pay"
        }
      ]
    }
    ```

Note that this object might change between checkouts as APMs are not offered for all currencies and amounts, and we are continuously introducing new APMs for you to offer.

We recommend handling the returned payment methods as an allowlist for this checkout, and then picking all the payment methods you want to offer. Do **not** simply display all methods returned if your integration doesn't support them.

The customer chooses one of the payment methods from the returned values, sent as part of the process checkout request under `payment_type`.

The currently available payment method ids are: `card`, `ideal`, `bancontact`, `boleto`, `eps`, `mybank`, `satispay`, `blik`, `p24`, `pix`, `qr_code_pix`, `apple_pay`, `paypal`, `google_pay`. _name_ is just for display purposes.

APMs differ from the behavior of cards. There are two possible flows, which we call `artifacts` or `redirect instructions`, explained in more detail below. APMs also require different input parameters obtained from the customer, as listed below:

| Payment method name | Parameters                                          | Flow     |
| ------------------- | --------------------------------------------------- | -------- |
| bancontact          | First name, Last name, Country                      | Redirect |
| blik                | First name, Last name, Country, Email               | Redirect |
| boleto              | First name, Last name, Country, Email, Address, CPF | Artifact |
| eps                 | First name, Last name, Country, Email               | Redirect |
| ideal               | First name, Last name, Country, Email               | Redirect |
| myBank              | First name, Last name, Country, Email               | Redirect |
| p24                 | First name, Last name, Country, Email               | Redirect |
| satispay            | First name, Last name, Country, Email               | Redirect |
| pix                 |                                                     | Artifact |
| qr_code_pix         |                                                     | Artifact |

Example payload:

```json
{
  "payment_type": "#Payment method name",
  "personal_details": {
    "email": "#Email",
    "first_name:": "#First Name",
    "last_name": "#Last Name",
    "tax_id": "#CPF",
    "address": {
      "country": "#Country",
      "city": "#Address",
      "line1": "#Address",
      "postal_code": "#Address",
      "state": "#Address"
    }
  }
}
```

### Process Checkout Using Redirect Flow

In the Redirect Flow, when the checkout is processed, you receive the `"status": "pending"` parameter and the `next_step` parameter, which means an additional action is required to process the payment.Example response:

```json
{
  ...
  "status": "pending",
  "next_step": {
    "url": "https://apm-redirect-link",
    "method": "POST",
    "payload": {
      "....": "..."
    }
  },
  ...
}
```

Most of the time, this is a simple redirect to a 3rd party page, like Blik, where the customer can pay.
But, as shown above, POST requests are also possible. For all calls, ensure that the payload is included, and the appropriate method is used.
Once the customer completes the necessary actions on the page, they are redirected to the `redirect_url` specified under the [create checkout request](/api/checkouts/create).
Now you can retrieve the final status via a [GET checkout request](/api/checkouts/get/).

### Process Checkout Using Payment Method Artifacts Flow

Payment method artifacts are images, PDFs etc. which the customer gets in order to pay. Currently, we have 3 payment methods which have artifacts: `boleto`, `pix` and `qr_code_pix`.

Example requests for each:

**boleto:**

```json
{
  "boleto": {
    "barcode": "23790001246004987209031123456704579990000010000",
    "url": "https://api.sumup.com/v0.1/checkouts/19c11c6c-be1d-4dd6-b718-2798878117cb/boletos/1044833949",
    "valid_until": "2022-02-01T17:57:10.442+00:00",
    "artefacts": [
      {
        "name": "invoice",
        "content_type": "application/pdf",
        "location": "https://homolog.meiosdepagamentobradesco.com.br/apiboleto/Bradesco?token=bWJvYXpkc1hXRzdhRVkyUUFGZUV4T25NYjBVVEZrNG93Y3RKLzM4cTh5dWdDWEh5dDQyTXN6ZHl5NFdjaHBkZg..",
        "created_at": "2022-01-21T17:57:10.443+00:00"
      },
      {
        "name": "code",
        "content_type": "text/plain",
        "location": "https://api.sumup.com/v0.1/artefacts/5266b29e-625b-43c0-a74a-8985ea3acd8a/content",
        "content": "23790001246004987209031123456704579990000010000",
        "created_at": "2022-01-21T17:57:10.445+00:00"
      }
    ]
  }
}
```

**pix:**

```json
{
  "pix": {
    "artefacts": [
      {
        "name": "barcode",
        "content_type": "image/jpeg",
        "location": "https://api.sumup.com/v0.1/artefacts/ee69508f-1b16-4ead-8416-8d2085933e6f/content",
        "created_at": "2021-10-12T22:06:46.327+00:00"
      },
      {
        "name": "code",
        "content_type": "text/plain",
        "location": "https://api.sumup.com/v0.1/artefacts/1e1e5130-17d1-495a-8e36-2a50d40dacde/content",
        "content": "00020126580014br.gov.bcb.pix0136a4fac492-d03b-45a8-bd43-c3f23d4bac68520400005303986540520.005802BR5916Priscila Manhaes6009Sao Paulo62290525SUMUP202110122206453822986304A61E",
        "created_at": "2021-10-12T22:06:46.326+00:00"
      }
    ]
  }
}
```

**qr_code_pix:**

```json
{
  "qr_code_pix": {
    "artefacts": [
      {
        "name": "barcode",
        "content_type": "image/jpeg",
        "location": "https://api.sam-app.ro/v0.1/artefacts/ee69508f-1b16-4ead-8416-8d2085933e6f/content",
        "created_at": "2021-10-12T22:06:46.327+00:00"
      },
      {
        "name": "code",
        "content_type": "text/plain",
        "location": "https://localhost:3000/v0.1/artefacts/1e1e5130-17d1-495a-8e36-2a50d40dacde/content",
        "content": "00020126580014br.gov.bcb.pix0136a4fac492-d03b-45a8-bd43-c3f23d4bac68520400005303986540520.005802BR5916Priscila Manhaes6009Sao Paulo62290525SUMUP202110122206453822986304A61E",
        "created_at": "2021-10-12T22:06:46.326+00:00"
      }
    ]
  }
}
```

The major difference between `qr_code_pix` and `pix` is that `pix` is paid directly into the merchant's SumUp bank account if they have one. `qr_code_pix` is paid out with the normal payout process and incurs a fee.

For all artifact payments, you need to provide the customer with the artifact and wait for the checkout to eventually complete.

Once the user has paid, you can retrieve the final status via the [GET checkout request](/api/checkouts/get/).