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 <a href="https://en.wikipedia.org/wiki/ISO_4217" target="_blank" rel="noopener">ISO4217</a> 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 (<a href="https://en.wikipedia.org/wiki/List_of_postal_codes_in_Brazil" target="_blank">more information about the format available here</a>). 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 <a href="https://en.wikipedia.org/wiki/ISO_4217" target="_blank" rel="noopener">ISO4217</a> 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]

    Currrent status of the checkout.

  • date date-time

    Date and time of the creation of the payment checkout. Response format expressed according to <a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank" rel="noopener">ISO8601</a> 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.