Create Payment

post

https://api-sandbox.koin.com.br/v1/payment/orders

This is the single, unified endpoint for creating a payment across all supported methods
(Pix, Card, Bnpl, Modo, GooglePay, Debin, ApplePay, AstroPay, PayPal, SafetyPay).
Select the method exclusively via payment_method.code — there is no separate request shape per method, per integration (direct API, SDK, checkout) or for antifraud.
Each method has one request that covers all of its modes: add the checkout, antifraud or consent fields to the same payload as needed.

This service facilitates the creation of a new order within the system. Depending on the specified flow and payment method, the request initiates one of the following processes:

Direct Charge: Immediate processing of the collection.
Debt Posting: Registration of a pending obligation for future settlement.
Payment Link: Generation of a unique URL for customer checkout.
SDK Execution: Initialization of an order to be processed via the KOIN SDK.

This endpoint serves as the primary entry point for the transaction lifecycle, capturing all essential sales metadata and establishing the foundation for the subsequent collection workflow.

Body Params

store

object

Store information

transaction

object

required

Transaction details

country_code

string

required

Transaction country code (two-letter ISO 3166 country code)

channel

string

enum

May be used with ASTRO_PAY, PAYPAL, and SAFETY_PAY payments.

Allowed:

payment_method

required

Payment method configuration. This is the sole selector for the payment method —
choose one of the available types via the code discriminator below.

payer

object

Payer information. May be used with CARD, GOOGLE_PAY, APPLE_PAY, and BNPL payments.

buyer

object

Buyer information. Different from payer. May be used with CARD antifraud, PAYPAL, and SAFETY_PAY payments.

items

array

Purchase items. May be used with CARD antifraud, BNPL, and PAYPAL payments.

items

shipping

object

Shipping information. May be used with CARD antifraud and BNPL payments.

redirect_url

object

Redirect URLs. May be used for checkout transactions and antifraud strategies with PIX, CARD, ASTRO_PAY, PAYPAL, and SAFETY_PAY payments.

device

object

May be used with CARD antifraud and BNPL payments.

verified_id

boolean

Indicates if the buyer's ID was verified. May be used with BNPL payments.

mobile

boolean

Indicates you want a mobile checkout experience.

terms

object

Terms and conditions. May be used with BNPL Transparent Checkout payments.

descriptor

string

Description sent to recipient of payment (Max. 140 characters)

notification_url

array of strings

List of urls to which notifications will be sent

notification_url

consent

object

Consent for recurring charges / card-on-file. May be used with CARD payments.

split

array of objects

Optional payment split configuration (list of sellers).

split

Responses

404

Not Found

409

Conflict

500

Internal Server Error

200Create payment response

400Bad Request