Skip to main content

Create a checkout​

Creates a new payment checkout resource. The unique checkout_reference created by this request, is used for further manipulation of the checkout.

For 3DS checkouts, add the redirect_url parameter to your request body schema.

Follow by processing a checkout to charge the provided payment instrument.

Request Body
  • checkout_reference string required

    Possible values: <= 90 characters

    Unique ID of the payment checkout specified by the client application when creating the checkout resource.

  • amount float required

    Amount of the payment.

  • currency string required

    Possible values: [BGN, BRL, CHF, CLP, CZK, DKK, EUR, GBP, HRK, HUF, NOK, PLN, RON, SEK, USD]

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

  • merchant_code string required

    Unique identifying code of the merchant profile.

  • pay_to_email email

    Email address of the registered user (merchant) to whom the payment is made. It is highly recommended to use merchant_code instead of pay_to_email.

  • description string

    Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.

  • return_url uri

    URL to which the SumUp platform sends the processing status of the payment checkout.

  • customer_id string

    Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referrenced customer.

  • redirect_url string

    Required for 3DS checkouts. Refers to a url where the end user is redirected once the payment processing completes.

  • payment_type string

    Alternative payment method name

  • personal_details object

    Object containing personal details about the payer, typical for Boleto checkouts

  • email string

    Payer's email address

  • first_name string

    Payer's first name

  • last_name string

    Payer's last name

  • tax_id string

    Payer's tax identification number (CPF)

  • address object

    Payer's address information

  • country string

    Payer's country

  • city string

    Payer's city

  • line_1 string

    Field for address details

  • state string

    Possible values: [AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO]

    Payer's state code

  • postal_code integer

    Possible values: Value must match regular expression ^\d{5}-?\d{3}$

    Payer's postal code. Must be eight digits long, however an optional dash could be applied after the 5th digit (more information about the format available here). Both options are accepted as correct.

Responses

Created

Schema
  • checkout_reference string

    Possible values: <= 90 characters

    Unique ID of the payment checkout specified by the client application when creating the checkout resource.

  • amount float

    Amount of the payment.

  • currency string

    Possible values: [BGN, BRL, CHF, CLP, CZK, DKK, EUR, GBP, HRK, HUF, NOK, PLN, RON, SEK, USD]

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

  • pay_to_email email

    Email address of the registered user (merchant) to whom the payment is made.

  • merchant_code string

    Unique identifying code of the merchant profile.

  • description string

    Short description of the checkout visible in the SumUp dashboard. The description can contribute to reporting, allowing easier identification of a checkout.

  • return_url uri

    URL to which the SumUp platform sends the processing status of the payment checkout.

  • id string

    Unique ID of the checkout resource.

  • status string

    Possible values: [PENDING, FAILED, PAID]

    Current status of the checkout.

  • date date-time

    Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

  • valid_until date-time

    Date and time of the checkout expiration before which the client application needs to send a processing request. If no value is present, the checkout does not have an expiration time.

  • customer_id string

    Unique identification of a customer. If specified, the checkout session and payment instrument are associated with the referrenced customer.

  • mandate object

    Created mandate

  • type string

    Indicates the mandate type

  • status string

    Mandate status

  • merchant_code string

    Merchant code which has the mandate

  • transactions object[]

    List of transactions related to the payment.