---
title: "Payment Method Events"
method: POST
path: "payment_method.events"
tags: ["Webhooks"]
---

# Payment Method Events

`POST payment_method.events` (webhook)

Afriex delivers real-time notifications to your configured webhook URL whenever a payment method is **created**, **updated**, or **deleted** for a customer.

A call to `GET /api/v1/payment-method/pool-account` also sends `PAYMENT_METHOD.UPDATED` for the pool account, on every call.

The payload structure is **identical** across all events. Only the `event` field changes.

**Security**: Every request includes an `x-webhook-signature` header and an `x-afriex-business-id` header carrying your business id. You **must** verify this signature using Afriex's public key before processing. The key is an elliptic-curve (secp384r1 / P-384) key, not RSA. The signature is ECDSA with SHA-256, DER-encoded and then base64-encoded, computed over the exact raw request body, so verify it before parsing or re-serialising the JSON. See the [Webhooks Overview & Security](https://docs.afriex.com/api-reference/endpoint/webhooks/introduction) section for verification instructions.

## Payload

- object
  - `id` string, uuid, required: Unique ID of this event. Every delivery attempt of the same event carries the same `id`, so use it to ignore a delivery you have already processed.
  - `event` 'PAYMENT_METHOD.CREATED' | 'PAYMENT_METHOD.UPDATED' | 'PAYMENT_METHOD.DELETED', required: Identifies which payment method event occurred
  - `createdAt` string, date-time, required: When Afriex created the event. Retries keep this value, and the signature covers it, so you can reject a delivery that is older than you expect.
  - `data` PaymentMethod, required: A payment method. Empty fields are omitted. Account-shaped channels (BANK_ACCOUNT, MOBILE_MONEY, SWIFT, etc.) populate accountName, accountNumber, and institution; the CARD channel instead populates last4, brand, expiration, and cardName.
    - `paymentMethodId` string: The unique identifier for the payment method.
    - `customerId` string: The unique identifier of the customer.
    - `reference` string: Identifier to reconcile incoming deposits against.
    - `institution` PaymentMethodInstitution: On a payment method, only `institutionId`, `institutionName`, `institutionCode`, `institutionAddress` and the correspondent bank fields are returned. The address components and `institutionBranch` are accepted when you create one but are not returned on it; `institutionBranch` is returned by the institution list.
      - `institutionId` string: The unique identifier of the bank or mobile money provider if required.
      - `institutionName` string: The name of the bank or mobile money provider if required.
      - `institutionCode` string: The code of the bank or mobile money provider.
      - `institutionAddress` string: The address of the bank or mobile money provider if required.
      - `institutionAddressLine1` string: Optional. First line of `institutionAddress`, for SWIFT payment methods. Used ahead of `recipientAddressLine1`.
      - `institutionAddressCity` string: Optional. City of `institutionAddress`, for SWIFT payment methods.
      - `institutionAddressState` string: Optional. State of `institutionAddress`, for SWIFT payment methods.
      - `institutionAddressZip` string: Optional. Postal or ZIP code of `institutionAddress`, for SWIFT payment methods.
      - `institutionAddressCountry` string: Optional. Country of `institutionAddress`, for SWIFT payment methods.
      - `institutionBranch` string: The branch of the bank. Required when creating a BANK_ACCOUNT payment method in CNY. Bank lists return it too, often as an empty string.
      - `correspondentBankName` string: The correspondent (intermediary) bank name. Mandatory for USD (SWIFT) payout payment methods; required to produce settlement advices/invoices.
      - `correspondentBankAccountNumber` string: The correspondent (intermediary) bank account number. Mandatory for USD (SWIFT) payout payment methods; required to produce settlement advices/invoices.
    - `transaction` PaymentMethodTransaction
      - `transactionInvoice` string: The invoice filename (S3 object key) for the transaction, as returned by the media upload endpoint.
      - `transactionNarration` string: The optional reason for the transaction.
    - `recipient` PaymentMethodRecipient: On a payment method, only `recipientEmail`, `recipientPhone`, `recipientAddress` and `recipientName` are returned. The other fields are accepted when you create one but are not returned on it.
      - `recipientEmail` string, email: The email address of the recipient if needed.
      - `recipientPhone` string: The phone number of the recipient in E.164 format.
      - `recipientAddress` string: The address of the recipient if needed.
      - `recipientAddressLine1` string: Optional. First line of `recipientAddress`. Used on SWIFT payment methods when `institutionAddressLine1` is not sent.
      - `recipientAddressCity` string: Optional. City of `recipientAddress`.
      - `recipientAddressState` string: Optional. State of `recipientAddress`.
      - `recipientAddressZip` string: Optional. Postal or ZIP code of `recipientAddress`.
      - `recipientAddressCountry` string: Optional. Country of `recipientAddress`.
      - `recipientIdType` 'national_id' | 'passport' | 'drivers_license' | 'voters_card' | 'residence_permit' | 'bvn' | 'tax_id': The type of the recipient's ID. Needed, with `recipientIdNumber`, for BANK_ACCOUNT payment methods in CNY, where it is recorded as the recipient's KYC.
      - `recipientIdNumber` string: The number of the ID named by `recipientIdType`. Needed for BANK_ACCOUNT payment methods in CNY.
      - `recipientUpiId` string: The recipient's UPI ID. Used on UPI payment methods; when omitted, `accountNumber` is used.
      - `recipientName` string: The name of the recipient if needed.
    - `channel` 'BANK_ACCOUNT' | 'MOBILE_MONEY' | 'SWIFT' | 'INTERAC' | 'UPI' | 'WE_CHAT' | 'ALIPAY' | 'CARD' | 'CRYPTO' | 'VIRTUAL_BANK_ACCOUNT' | 'POOL_ACCOUNT' | 'ACH_BANK_ACCOUNT' | 'PAYBILL_TILL' | 'RFP' | 'VIRTUAL_CARD': The payment method channel.
    - `countryCode` string: The ISO 3166-1 alpha-2 country code.
    - `currency` string: The payment method's currency (ISO 4217). Use this instead of inferring currency from countryCode, which is ambiguous (e.g. a USD account in a non-US country).
    - `capabilities` string[]: The operations this payment method is enabled for (e.g. DEPOSIT, WITHDRAW). Use it to select deposit-capable vs withdraw-capable methods. Also filterable via the `capabilities` query parameter.
    - `accountName` string: Name of the account holder. Present for account-shaped channels.
    - `accountNumber` string: Account number. Present for account-shaped channels, except INTERAC, which returns none. For UPI it carries the recipient phone number, not the UPI ID.
    - `routingNumber` string: Bank routing number. Present for account-shaped channels that carry one (e.g. ACH bank accounts).
    - `bankAddress` PaymentMethodBankAddress: The issuing bank's postal address, populated per account by the provider that provisioned it. Present on virtual accounts and other account-shaped payment methods whose provider supplies it; omitted otherwise. This is the bank's address, not the account holder's.
      - `line1` string: First line of the bank's street address.
      - `line2` string: Second line of the bank's street address, when present.
      - `city` string: City.
      - `state` string: State or region, when present.
      - `zip` string: Postal or ZIP code.
      - `country` string: Country, as supplied by the provider.
    - `status` 'active' | 'pending' | 'deleted' | 'expired' | 'blocked': Lifecycle status of the payment method.
    - `last4` string: Last 4 digits of the card. CARD channel only.
    - `brand` 'Visa' | 'MasterCard' | 'Discover' | 'American Express' | 'JCB' | 'Diners Club' | 'Eftpos Australia' | 'UnionPay' | 'Unknown': Card brand. CARD channel only.
    - `expiration` object: Card expiration. CARD channel only.
      - `month` integer
      - `year` integer
    - `cardName` string: Name on the card. CARD channel only.
    - `expiresInMinutes` integer: Minutes until a dynamic virtual account expires, when applicable.
    - `amount` union: The amount stored with the payment method, as you sent it (a number or a numeric string), or the requested amount for a dynamic virtual account, when applicable.
      - number
      - string
    - `extra` object: Additional channel-specific properties.
    - `meta` object: The meta data you attached to the payment method when you created it.

## Acknowledgement `200`

Acknowledge receipt. Return any 2xx status code quickly. Response body is ignored.

## Other responses

- `400`: Bad Request, malformed payload, invalid/missing signature, etc. Afriex will retry delivery.
- `401`: Unauthorized, signature verification failed.

---

[API](https://skmtc.dev/afriex/apis/afriex-business-api.md) - [All operations](https://skmtc.dev/afriex/apis/afriex-business-api/llms.txt) - [OpenAPI document](https://skmtc.dev/afriex/apis/afriex-business-api/revisions/d94198b6c256?raw)