Instruction created

Fires when a payment instruction is added to a beneficiary; the new instruction starts in PENDING_REVIEW.

WEBHOOK BENEFICIARY_PAYMENT_INSTRUCTION_CREATED

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.