Payment Services

Create Payment

Changed on Nov 3, 2026

This is the single, unified endpoint for creating a payment across all supported methods (Pix, Card, Bnpl, Modo, GooglePay, Debin, ApplePay, AstroPay, PayPal, SafetyPay, Itaú Pay). 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.

post/v1/payment/orders

Request

Base URL
https://api-sandbox.koin.com.br
URL
https://api-sandbox.koin.com.br/v1/payment/orders
Auth
none declared. Required headers: Content-Type, Accept

Headers

Content-Typestring required

The Media type of the body of the request. Default value for payment provider protocol is application/json

Acceptstring required

Media type(s) that is/are acceptable for the response. Default value for payment provider protocol is application/json

Request body

country_codestring required

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

channel'API' | 'CHECKOUT' | 'SDK'

Integration channel used to process the payment. If omitted in the request, it is assigned automatically based on the payment method and merchant account configuration.

verified_idboolean

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

mobileboolean

Indicates you want a mobile checkout experience.

descriptorstring

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

notification_urlstring[]

List of urls to which notifications will be sent

Example request

{
  "store": {
    "code": "SBXSTORE",
    "category": "4816"
  },
  "transaction": {
    "reference_id": "REF0000001",
    "business_id": "BIZ0000001",
    "account": "SBX000",
    "amount": {
      "currency_code": "BRL",
      "value": 1500.56,
      "breakdown": {
        "items": {
          "currency_code": "BRL",
          "value": 1000
        },
        "shipping": {
          "currency_code": "BRL",
          "value": 500.56
        },
        "taxes": {
          "currency_code": "BRL"
        },
        "fee": {
          "currency_code": "BRL"
        }
      }
    }
  },
  "country_code": "BR",
  "channel": "API",
  "payment_method": {
    "expiration_date": "2025-12-31T23:59:59.000Z",
    "payment_key": "sbx@paymentKey"
  },
  "payer": {
    "document": {
      "number": "54672396002",
      "nationality": "BR"
    },
    "first_name": "Jhon",
    "last_name": "Doe",
    "full_name": "Jhon Doe Jones",
    "name_father": "Doe",
    "name_mother": "Jones",
    "email": "jhon_doe@domain.com",
    "phone": {
      "country_code": "+55",
      "area": "11",
      "number": "984565666",
      "type": "Mobile"
    },
    "birthdate": "1980-10-20",
    "address": {
      "country_code": "BR",
      "state": "SP",
      "city_name": "SAO PAULO",
      "street": "RUA ABRAO WAITMAN",
      "number": "500",
      "zip_code": "04788240",
      "district": "INTERLAGOS"
    }
  },
  "buyer": {
    "id": "c1245228",
    "first_name": "Alvaro",
    "last_name": "Garrincha",
    "full_name": "Alvaro Garrincha",
    "document": {
      "nationality": "UY",
      "number": "35645888",
      "type": "DNI"
    },
    "address": {
      "city": "Buenos Aires",
      "complement": "Complemento",
      "country_code": "AR",
      "neighborhood": "Chacarita",
      "number": "2459",
      "state": "Buenos Aires",
      "street": "Corrientes",
      "zip_code": "1425",
      "full_address": "Corrientes 747, San Nicolas"
    },
    "birth_date": "1990-05-06",
    "email": "email@domain",
    "phone": {
      "area_code": "11",
      "number": "45669874",
      "type": "Mobile"
    },
    "profile": {
      "category": "1"
    }
  },
  "items": [
    {
      "category": {
        "id": "111",
        "name": "Some category name"
      },
      "discount_amount": {
        "currency_code": "USD",
        "value": 8008.99
      },
      "id": "13238487",
      "name": "Some name",
      "price": {
        "currency_code": "USD",
        "value": 8008.99
      },
      "quantity": 5,
      "seller_id": "Some Seller",
      "service_date": "2021-01-01T00:00:00.000Z"
    }
  ],
  "shipping": {
    "delivery_date": "2021-11-01",
    "address": {
      "country_code": "BR",
      "state": "SP",
      "city_name": "SAO PAULO",
      "street": "RUA ABRAO WAITMAN",
      "number": "500",
      "zip_code": "04788240",
      "district": "INTERLAGOS"
    },
    "price": {
      "currency_code": "USD",
      "value": 8008.99
    }
  },
  "redirect_url": {
    "success_url": "https://www.provider.com/successUrl",
    "cancel_url": "https://www.provider.com/cancelUrl",
    "failed_url": "https://www.provider.com/failedUrl",
    "antifraud_url": "https://www.provider.com/antifraudUrl"
  },
  "device": {
    "ipv4": "186.134.179.26",
    "ipv6": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
    "session_id": "armor.6d9c2f6da88a9c22aeca9d0e2773fc7d4496cd76b438327cb1408f13dbad30cc",
    "merchant_device": "234c20c3-45de-41bf-b243-87ad5RTbc3b",
    "location": {
      "latitude": -34.5653,
      "longitude": -58.4894
    }
  },
  "terms": {
    "accepted": true
  },
  "notification_url": [
    "https://www.providerApi.com/notificationPayments"
  ],
  "consent": {
    "operation": "INITIAL",
    "triggered": "SCHEDULED",
    "customer_reference": "CUST-0001",
    "billing_date": "2026-08-01T00:00:00.000Z"
  },
  "split": [
    {
      "seller_id": "SELLER-0001",
      "role": "PARTICIPANT",
      "amount": {
        "value": 100,
        "percentage": 30,
        "currency_code": "BRL"
      },
      "chargeback_liable": true,
      "processing_fee": "NONE",
      "document": {
        "type": "CNPJ",
        "number": "12345678000199"
      }
    }
  ]
}

Response

Create payment response

Example response

{
  "store": {
    "code": "SBXSTORE"
  },
  "transaction": {
    "reference_id": "REF0000001",
    "business_id": "BIZ0000001",
    "amount": {
      "currency_code": "BRL",
      "value": 1500.56
    },
    "provider_reference": {
      "order_id": "6a5f5159-c5dc-43b2-b3d4-34471d9be94c",
      "payment_id": "82106789179776-1"
    }
  },
  "order_id": "9dd3f765-a51a-49d8-b6af-a51d5a0b3f7f",
  "status": {
    "error": {
      "code": "G01",
      "message": "Gateway, payment method not supported"
    }
  },
  "country_code": "BR",
  "channel": "API",
  "locations": [
    {
      "url": "pix.example.com/qr/9d36b84f-c70b-478f-b95c-12729b90ca25"
    }
  ],
  "return_url": "https://payments.koin.com.br/checkout/2609bd4a-60ba-8fb6-ac9f-0b28f67f679e"
}

Changes

Nov 3, 20261e3734785750 Revision changes
- breaking
  added the new required request property
- breaking
  added the new required request property
- breaking
  added the new required request property
- breaking
  removed from the request body oneOf list
- breaking
  the request's body type changed from no type to object
- breaking
  added to the response body oneOf list for the response status
- breaking
  removed the required property /// from the response with the status
- warning
  added the new Collected enum value to the // response property for the response status
- warning
  added the new Voided enum value to the // response property for the response status
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  removed the LINK enum value from the / response property for the response status
- info
  removed the LINK enum value from the / response property for the response status
- info
  removed the LINK enum value from the / response property for the response status
- info
  the /// response's property pattern was changed from ^\d{1,10}\.\d{2}$ to d{1,10}.d{2} for the status
- info
  the // response's property pattern was changed from ^\d{1,10}\.\d{2}$ to d{1,10}.d{2} for the status
- info
  the // response's property pattern was changed from ^\d{1,10}\.\d{2}$ to d{1,10}.d{2} for the status
- info
  the // response's property pattern was changed from ^\d{1,10}\.\d{2}$ to d{1,10}.d{2} for the status
- info
  the // response's property pattern was changed from ^\d{1,10}\.\d{2}$ to d{1,10}.d{2} for the status
- info
  the // response's property pattern was changed from ^\d{1,10}\.\d{2}$ to d{1,10}.d{2} for the status
- info
  the // response's property pattern was changed from ^\d{1,10}\.\d{2}$ to d{1,10}.d{2} for the status
- info
  the // response's property pattern was changed from ^\d{1,10}\.\d{2}$ to d{1,10}.d{2} for the status
- info
  the // response's property pattern was changed from ^\d{1,10}\.\d{2}$ to d{1,10}.d{2} for the status
- info
  the /// response's property pattern was changed from ^\d{1,10}\.\d{2}$ to d{1,10}.d{2} for the status
- info
  the /// response's property pattern was changed from ^\d{1,10}\.\d{2}$ to d{1,10}.d{2} for the status

Operation history