Instruction approved

Fires when a payment instruction on a beneficiary is approved. Carries the affected instruction plus beneficiary context.

WEBHOOK BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED

Example

{
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "entity": {
    "type": "INDIVIDUAL",
    "firstName": "John",
    "lastName": "Doe",
    "taxId": "12345678901",
    "dateOfBirth": "1990-01-15",
    "address": {
      "addressLine1": "Rua Augusta, 500",
      "city": "São Paulo",
      "country": "BR",
      "postalCode": "01304-001",
      "addressLine2": null,
      "state": "SP"
    }
  },
  "instruction": {
    "asset": "BRL",
    "currentState": {
      "createdAt": "2023-11-07T05:31:56Z",
      "reason": {
        "code": "INSUFFICIENT_BALANCE",
        "message": "Insufficient balance for the requested operation",
        "details": {}
      }
    },
    "address": {
      "type": "PixKey",
      "rail": "PIX_KEY",
      "key": "12345678901"
    }
  },
  "atTime": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.

Body

application/json

Payload delivered for beneficiary payment-instruction lifecycle events (BENEFICIARY_PAYMENT_INSTRUCTION_CREATED, BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED, BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED). Each event corresponds to one payment instruction transition. The payload includes the affected instruction plus enough beneficiary context (id, customerId, entity, relationshipType) to act on the event without an extra lookup. To see the full set of payment instructions attached to a beneficiary, call GET /api/beneficiaries/{beneficiaryId} on the fx-payment API.

customerId · string<uuid> · required

entity · Individual · object · required

Beneficiary entity. Discriminated by type.

Individual

Company

Show child attributes

relationshipType · enum<string> · required

Whether the beneficiary is the customer themselves (SELF_OWNED) or a separate party (THIRD_PARTY).

Available options: SELF_OWNED, THIRD_PARTY

instruction · object · required

A payment instruction attached to a beneficiary, with full address and review status.

Show child attributes

atTime · string<date-time> · required

When this event occurred. Distinct from the resource's createdAt — events fire on state transitions, so atTime reflects when the transition happened, not when the underlying resource was first created.

Response

200

Acknowledged. Trace Finance considers any 2xx response a successful delivery.