Skip to main content
Use the /payins endpoint to create a payment request that your customer will complete using one of the supported payment methods.

​
General flow

  1. Send a POST request to /payins with the amount, customer data, selected rail, and method-specific details.
  2. HelloPay creates the payin and returns its initial state.
  3. For async rails, poll the payin until the source data needed to continue the flow is available.
  4. The customer completes the payment using the selected payment method.
  5. HelloPay updates the payin status asynchronously and sends webhook events.
  6. After the flow ends, the user is redirected to the callbackUrl you provided.

​
Polling behavior

For async payin rails such as PSE and BRE_B, the creation response can omit some source data until HelloPay finishes preparing the flow.
  • In PSE payins, sourceData.pseUrl is returned as null right after creation.
  • In BRE_B payins, sourceData depends on breb.keyType. SINGLE_USE returns the generated key, and QR_CODE also returns sourceData.qrString with the QR image payload.
  • Poll the payin after creation to retrieve the updated sourceData values once HelloPay finishes populating them.
  • The method-specific guides include request and response examples for each async flow.

​
Common fields

These fields are shared across all payin methods:
  • amountInCents: amount to collect in cents.
  • currency: currently COP.
  • rail: payment method to use, such as PSE or BRE_B.
  • reference: your internal payment reference.
  • inlineCustomer: customer information used during the payment flow.
  • callbackUrl: URL where the payer is redirected after completing the payment.

​
Supported document types

Use one of the following values in inlineCustomer.idType:
ValueDescription
PASSPORTPassport document.
CO_CCColombian citizenship ID.
CO_NITColombian tax identification number for businesses.
CO_CEColombian foreigner ID card.

​
Supported payment methods

​
Sample payin response

The creation response keeps the same base shape regardless of the selected payment method. 
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 10000,
  "currency": "COP",
  "status": "PROCESSING",
  "rail": "PSE",
  "reference": "1dwDmHerYL5NBQZ",
  "inlineCustomer": {
    "name": "John Doe",
    "idType": "CO_CC",
    "idNumber": "1000000001",
    "email": "john.doe@doe.com",
    "phone": "+573131111111"
  },
  "errorCode": null,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "resultAt": null,
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "sourceData": {
    "paymentMethod": "PSE"
  },
  "callbackUrl": "https://portal.hellopay.com.co"
}
For method-specific payloads and examples, follow the dedicated guides for each payment method.