Alternative Payment Methods (APMs) Integration Guide

General

Alternative Payment Methods, from now on referred to as APMs. APM checkouts are very similar to normal checkouts. The biggest difference is that the customer most of the time needs to take an additional action in order to finalize the payment. Please make sure that before you read this you familiarize yourself with how card payments are done.

First, you need to know which payment methods are available to your merchant profile. To check this 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.

The response will look like this

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

Note here that this is not a static list and might change from checkout to checkout as payment methods are not offered for all currencies and amounts, and we are continuously introducing new APMs you can include in your list of payment options.

Our suggestion would be to handle the returned payment methods as an allowlist for this checkout, and then from this list pick all the payment methods you want/can offer. Do not display all methods returned if you can not handle their respective flows.

The customer chooses one of the payment methods from the returned values, which should be 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, giropay, pix, qr_code_pix, apple_pay, paypal, google_pay. name is just for display purposes.

APMs differ from the behaviour 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 which you need to gather from the customer. The required parameters to gather and the payment method flows are listed below:

The payload needs to be filled out like this:

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

Redirect Flow

In the redirect flow when the checkout is processed you will receive the state “PENDING” and the response will include a next_step parameter, this means an additional action for the processing is needed. The response will look something like this:

{
  ...
  "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 in this example, you can also see that this might be a POST request. For all calls, you should make sure that the payload is included and the appropriate method is used. Once the customer completes the necessary actions on the page they will be redirected to the redirect_url specified under the create checkout request. Now you can retrieve the final status via a GET checkout call request.

Payment Method Artifacts

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. Examples of the type of information to expect can be found below:

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"
      }
    ]
  }
}

Note that the major difference between qr_code_pix and pix itself is that pix will be paid directly into the merchant's SumUp bank account if they have one. qr_code_pix will be 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 a GET checkout call.