Payment intents

The Payment Intent webhook comes into play during the process of executing a payment. When the user decides to create a Payment Intent, you will receive a response indicating whether the payment could be created or not.

Any subsequent status change (for example, if the payment was successful or if it requires some action from the Payer) will be notified by this webhook. After saving the information in Binco's database, it will send a notification to the URL configured for your company, keeping you informed of any developments in the payment process.

Payment intent in process

When the payment attempt is in process, you will receive a notification of type PAYMENT_INTENT_PROCESSING, like the following example:

{
  "webhookType": "PAYMENT_INTENT_PROCESSING",
  "paymentInstrumentExternalId?": "2a0495da-02bc-441c-b690-dbf8b399cd1f",
  "payerExternalId": "5029b7ee-bd4b-439f-9ec5-4377ff8c99dd",
  "merchantExternalId": "6e2d27e3-650d-41c7-a4f0-3ffc77e84ce8",
  "date": "2024-02-07 10:07:35.695152-03",
  "paymentIntent": {
    "paymentIntentId": "9f71923b-16b6-40da-8609-1c2736ee0802",
    "businessId": "aa0299d8-6375-4472-a36a-31c68641ee36",
    "payerId": "5029b7ee-bd4b-439f-9ec5-4377ff8c99dd",
    "paymentInstrumentId": "2a0495da-02bc-441c-b690-dbf8b399cd1f",
    "paymentIntentStatus": "PROCESSING",
    "payinType": "TRANSFER",
    "lastPaymentError": "",
    "externalReference": "1805",
    "externalChargeId": "5847952",
    "currency": "USD",
    "subtotalAmount": "100",
    "taxAmount": "0",
    "tipAmount": "0",
    "totalAmount": "100",
    "receivedAmount": "100",
    "confirmationMethod": "AUTOMATIC",
    "externalInvoiceId": "",
    "nextAction": "",
    "setupFutureUsage": false,
    "confirm": true,
    "metadata": "{\n  \"key\": \"one\",\n  \"other_key\": \"two\"\n}"
  }
}

The data type of the notification structure is as follows:

{
  webhookType: WebhookType,
  paymentInstrumentExternalId: uuid,
  payerExternalId: uuid,
  merchantExternalId: uuid,
  date: Date,
  paymentIntent: PaymentIntentData
}

enum WebhookType {
  PAYMENT_INSTRUMENT_SUCCESS = 'PAYMENT_INSTRUMENT_SUCCESS',
  PAYMENT_INSTRUMENT_FAILED = 'PAYMENT_INSTRUMENT_FAILED',
  PAYMENT_INTENT_PROCESSING = 'PAYMENT_INTENT_PROCESSING',
  PAYMENT_INTENT_SUCCESS = 'PAYMENT_INTENT_SUCCESS',
  PAYMENT_INTENT_FAILED = 'PAYMENT_INTENT_FAILED',
}

interface PaymentIntentData {
  externalReference: string;
  paymentIntentStatus: PaymentIntentStatus;
  payinType: PayinType;
  lastPaymentError: string;
  description: string;
  currency: Currency;
  subtotalAmount: number;
  taxAmount: number;
  tipAmount: number;
  totalAmount: number;
  receivedAmount: number;
  confirmationMethod: ConfirmationMethodType;
  externalChargeId: string;
  externalInvoiceId: string;
  nextAction: string;
  setupFutureUsage: string;
  statementDescriptor: string;
  offSession: boolean;
  confirm: boolean;
  metadata: JSON;
}

export enum PaymentIntentStatus {
  REQUIRES_PAYMENT_INSTRUMENT = 'REQUIRES_PAYMENT_INSTRUMENT',
  REQUIRES_CONFIRMATION = 'REQUIRES_CONFIRMATION',
  REQUIRES_ACTION = 'REQUIRES_ACTION',
  PROCESSING = 'PROCESSING',
  SUCCESSFUL = 'SUCCESSFUL',
}

enum PayinType {
  DEFAULT = 'DEFAULT',
  TRANSFER = 'TRANSFER',
}

export enum Currency {
  UYU = 'UYU',
  USD = 'USD',
  EUR = 'EUR',
  ARG = 'ARG',
}

export enum ConfirmationMethod {
  MANUAL = 'MANUAL',
  AUTOMATIC = 'AUTOMATIC',
}

If the payment attempt fails, you will receive a POST notification with a webHookType PAYMENT_INTENT_FAILED.

Payment intents

Payment intent in process​

Payment intent in process