Payment instruments

This webhook is used in the process of creating a Payment Instrument for the Payer. During this process, the user is redirected to a webpage where they can enter all the necessary information for the chosen type of Payment Instrument. For example, if they are adding a new credit card, there they can enter the number, cardholder's name, expiration date, etc.

Note: In our system, no sensitive data regarding the payment instrument being added is stored.

The duration of this process can vary, as it depends on when the user decides to enter these details. Regardless of the time it takes, the Payment Instrument webhook will receive the information of the new Payment Instrument and store it in the database. Then, it will send the information to the notification URL configured for your company, ensuring that you are also notified at the end of this process.

Payment Instrument added successfully

The type of notification you will receive in this case will be PAYMENT_INSTRUMENT_SUCCESS, and you will receive a POST notification like the following:

{
  "webhookType": "PAYMENT_INSTRUMENT_SUCCESS",
  "paymentInstrumentType": "CARD",
  "paymentInstrumentExternalId": "3b4a1779-70a8-48c5-b92b-066d36bc41a3",
  "payerExternalId": "f612112b-802d-496d-9650-880c09cb2f34",
  "merchantExternalId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b",
  "date": "2024-02-07 10:00:00.00-00",
  "additionalData": {
    "paymentInstrumentName": "MasterCard",
    "maskedPan": "539153XXXXXX4986",
    "expiration": "2024-03-14T15:19:37.064Z",
    "paymentInstrumentLogo": "https://test.com.uy/payment-methods/MasterCard.svg",
    "cardType": "Credit"
  }
}

The data type of the notification structure is as follows:

interface Notification {
  webhookType: WebhookType;
  paymentInstrumentType: PaymentInstrumentType;
  paymentInstrumentExternalId: uuid;
  payerExternalId: uuid;
  merchantExternalId: uuid;
  date: Date;
  additionalData: AdditionalData;
}

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',
}

enum PaymentInstrumentType {
  CARD = 'CARD',
  A2A = 'A2A',
  PIX = 'PIX',
}

interface AdditionalData {
  paymentInstrumentName: string;
  maskedPan: string;
  expiration: Date;
  paymentInstrumentLogo: string;
  cardType: string;
}

The structure of additionalData will depend on the paymentInstrumentType.