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.

Check Available APMs

Check which payment methods are available to your merchant profile.

1. Create a checkout 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:

   {
     "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:

{
  "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:

{
  ...
  "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. Now you can retrieve the final status via a GET checkout request.

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:

{
  "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:

{
  "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:

{
  "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.