Accept a Payment

Overview

This guide covers single payments over SumUp API, using customer-entered card details without associating it with a specific customer saved for the merchant user’s account. Ideal for quick checkout processing if you don’t want to use our Payment Widget.

You will go through the following steps:

1. Create a checkout
2. Complete a checkout

When you complete these steps, you will have processed a payment with a payment card entered by a customer.

Prerequisites

• SumUp merchant account with completed account details.
  • You can also use a test account.
• Registered client application with SumUp.
• Valid access token obtained either with the Authorization code flow or Client credentials flow.

Steps

1. Create a Checkout

To create a new checkout resource, make a POST request to the https://api.sumup.com/v0.1/checkouts endpoint.

Caution

Checkout request must be made in a server-to-server communication between your server and SumUp API.

Note

The table below lists only the required parameters for the request. For a full list, see the API Reference.

Attribute name	Description
checkout_reference	A unique string identifying the payment in your system. It must be unique for your application.
amount	The amount for which the payment is made.
currency	The three-letter ISO4217 code of the payment currency. It must match the currency registered for the specified merchant (see merchant_code).
merchant_code	The code of the registered SumUp merchant the payment is made.

Example request:

cURL

curl -X POST \
  https://api.sumup.com/v0.1/checkouts \
  -H "Authorization: Bearer $SUMUP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
        "merchant_code": "ME7RMQN3",
        "amount": 15.0,
        "currency": "EUR",
        "checkout_reference": "unique-checkout-ref-123"
      }'

Node.js

const checkout = await client.checkouts.create({
  merchant_code: merchantCode,
  amount: 15.0,
  currency: "EUR",
  checkout_reference: "unique-checkout-ref-123"
});

.NET

var checkout = await client.Checkouts.CreateAsync(new CheckoutCreateRequest
{
    MerchantCode = merchantCode,
    Amount = 15.0f,
    Currency = Currency.Eur,
    CheckoutReference = "unique-checkout-ref-123",
});

Java

var checkout = client.checkouts().createCheckout(
    CheckoutCreateRequest.builder()
        .merchantCode(merchantCode)
        .amount(15.0f)
        .currency(Currency.EUR)
        .checkoutReference("unique-checkout-ref-123")
        .build()
);

Go

checkout, err := client.Checkouts.Create(ctx, sumup.CreateCheckoutBody{
  MerchantCode:      merchantCode,
  Amount:            15.0,
  Currency:          "EUR",
  CheckoutReference: "unique-checkout-ref-123",
})

Python

checkout = client.checkouts.create(
    CreateCheckoutBody(
        merchant_code=merchant_code,
        amount=15.00,
        currency="EUR",
        checkout_reference="unique-checkout-ref-123",
    )
)

Rust

let checkout = client.checkouts().create(Some(CheckoutCreateRequest {
    merchant_code,
    amount: 15.,
    currency: Currency::EUR,
    checkout_reference: "unique-checkout-ref-123".into(),
    description: None,
    return_url: None,
    customer_id: None,
    purpose: None,
    id: None,
    status: None,
    date: None,
    valid_until: None,
    transactions: None,
    redirect_url: None,
})).await?;

PHP

$checkoutsService = $sumup->getCheckoutService();
$response = $checkoutsService->create(10, 'EUR', 'CO746453', 'docuser@sumup.com', 'Sample one-time payment');
$checkoutId = $response->getBody()->id;

The response contains a JSON body with the details of the created checkout resource. Note the identifier of the resource - you will need it for all operations on the resource, such as processing the payment in the next step.

The resource identifier is returned in the id attribute, or f14425c6-8bc1-4d02-957c-47573f762828 in the sample response below. The status attribute shows that the payment for this resource is pending and will be processed when you complete the checkout with the payment instrument details.

{
  "checkout_reference": "CO746453",
  "amount": 10,
  "currency": "EUR",
  "merchant_code": "ME7RMQN3",
  "description": "Sample one-time payment",
  "id": "f14425c6-8bc1-4d02-957c-47573f762828",
  "status": "PENDING",
  "date": "2018-09-28T13:47:01.832Z",
  "transactions": []
}

2. Complete a Checkout

To process the checkout and trigger the payment, make a PUT request to the https://api.sumup.com/v0.1/checkouts/{id} endpoint, where the value of the {id} path parameter is the identifier of the checkout resource.

Caution

This request must be made from your client, not from your server.

The request body should be a JSON object with the payment type (card) and the payment card details. For more information about the request, see the API Reference.

Example request for Step 1 checkout:

cURL

curl -X PUT \
  https://api.sumup.com/v0.1/checkouts/f14425c6-8bc1-4d02-957c-47573f762828 \
  -H "Authorization: Bearer $SUMUP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
        "payment_type": "card",
        "card": {
          "name": "Boaty McBoatface",
          "number": "4200000000000042",
          "expiry_month": "12",
          "expiry_year": "23",
          "cvv": "123"
        }
      }'

Node.js

const checkout = await client.checkouts.process("f14425c6-8bc1-4d02-957c-47573f762828", {
  payment_type: "card",
  card: {
    name: "Boaty McBoatface",
    number: "4200000000000042",
    expiry_month: "12",
    expiry_year: "23",
    cvv: "123",
  },
});

.NET

var checkout = await client.Checkouts.ProcessAsync(
    "f14425c6-8bc1-4d02-957c-47573f762828",
    new ProcessCheckout
    {
        PaymentType = "card",
        Card = new Card
        {
            Name = "Boaty McBoatface",
            Number = "4200000000000042",
            ExpiryMonth = "12",
            ExpiryYear = "23",
            Cvv = "123",
            Last4Digits = "0042",
            Type = CardType.Visa,
        },
    });

Java

var checkout = client.checkouts().processCheckout(
    "f14425c6-8bc1-4d02-957c-47573f762828",
    ProcessCheckout.builder()
        .paymentType(ProcessCheckoutPaymentType.CARD)
        .card(
            Card.builder()
                .name("Boaty McBoatface")
                .number("4200000000000042")
                .expiryMonth(CardExpiryMonth.fromValue("12"))
                .expiryYear("23")
                .cvv("123")
                .build()
        )
        .build()
);

Go

ctx := context.Background()
client := sumup.NewClient().WithAuth(os.Getenv("SUMUP_API_KEY"))

checkoutSuccess, err := client.Checkouts.Process(ctx, "f14425c6-8bc1-4d02-957c-47573f762828", sumup.ProcessCheckoutBody{
  Card: &sumup.Card{
    Cvv:         "123",
    ExpiryMonth: "12",
    ExpiryYear:  "23",
    Name:        "Boaty McBoatface",
    Number:      "4200000000000042",
  },
  PaymentType: sumup.ProcessCheckoutBodyPaymentTypeCard,
})

Python

from sumup.checkouts.resource import Card, ProcessCheckoutBody

checkout = client.checkouts.process(
    "f14425c6-8bc1-4d02-957c-47573f762828",
    ProcessCheckoutBody(
        payment_type="card",
        card=Card(
            name="Boaty McBoatface",
            number="4200000000000042",
            expiry_month="12",
            expiry_year="23",
            cvv="123",
        ),
    ),
)

Rust

let checkout = client
    .checkouts()
    .process(
        "f14425c6-8bc1-4d02-957c-47573f762828",
        sumup::resources::checkouts::ProcessCheckout {
            payment_type: "card".into(),
            installments: None,
            mandate: None,
            customer_id: None,
            token: None,
            personal_details: None,
            card: Some(sumup::resources::checkouts::Card {
                name: "Boaty McBoatface".into(),
                number: "4200000000000042".into(),
                expiry_month: "12".into(),
                expiry_year: "23".into(),
                cvv: "123".into(),
                zip_code: None,
                last_4_digits: "0042".into(),
                type_: "VISA".into(),
            }),
        },
    )
    .await?;

The response contains a JSON body with the details of the processed checkout resource in which the attributes related to the payment outcome are populated:

{
  "checkout_reference": "CO746453",
  "amount": 10.0,
  "currency": "EUR",
  "merchant_code": "ME7RMQN3",
  "description": "Sample one-time payment",
  "id": "f14425c6-8bc1-4d02-957c-47573f762828",
  "status": "PAID",
  "date": "2018-09-28T13:47:01.832Z",
  "transaction_code": "TFDCP3FLQ7",
  "transaction_id": "19aa3cca-89f6-42d2-b462-463b0b53e959",
  "transactions": [
    {
      "id": "19aa3cca-89f6-42d2-b462-463b0b53e959",
      "transaction_code": "TFDCP3FLQ7",
      "merchant_code": "ME7RMQN3",
      "amount": 10.0,
      "vat_amount": 0.0,
      "tip_amount": 0.0,
      "currency": "EUR",
      "timestamp": "2018-09-28T13:48:28.768Z",
      "status": "SUCCESSFUL",
      "payment_type": "ECOM",
      "entry_mode": "CUSTOMER_ENTRY",
      "installments_count": 1,
      "auth_code": "585388",
      "internal_id": 24118507
    }
  ]
}

Result

You have made a payment with a payment card entered by a customer without associating it with a specific customer saved for a merchant user’s account. If the payment is successful, the funds will be transferred to the merchant user according to the configured account settings.