How to create your first payin

​

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. Poll the payin when a rail needs more source data, such as a PSE redirect URL.
4. The customer completes the payment using the selected payment method.
5. HelloPay updates the payin status asynchronously and sends webhook events.
6. Hosted flows return the payer to the callbackUrl you provided when applicable.

​

Polling behavior

• 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.
• In NEQUI payins, sourceData.phone contains the payer’s mobile number. There is no redirect URL or QR code to wait for.
• For PSE and BRE-B, poll the payin after creation if the source data you need is not yet available. For Nequi, wait for a final status instead.
• The method-specific guides include request and response examples for each async flow.

​

Common fields

• amountInCents: amount to collect in cents.
• currency: currently COP.
• rail: payment method to use: PSE, BRE_B, or NEQUI.
• 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

​

Supported payment methods

• PSE payin guide: bank redirect flow using PSE.
• BREB payin guide: collection flow using a BREB key.
• Nequi payin guide: collect from a payer’s Nequi account using their mobile number.

​

Sample payin response

{
  "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"
}