Managing off-ramp local target details

❗️

This functionality is only for implementations in which funds are transferred directly between the beneficiary and Caliza with no intermediation from the integrator.

Overview

For implementations in which off-ramps are deposited directly in the beneficiaries' account, you can freely retrieve and update the off-ramp.

Upon update, we will ensure that the tax identifier of the new target matches the tax identifier we have on file for the beneficiary.

Updating local target for a beneficiary

The data that is submitted will vary based on the country of the beneficiary's target account.

Brazil (Pix)

curl --request PUT \
     --url https://sandbox.api.caliza.co/core-api/v1/beneficiaries/{beneficiaryId}/localTargetAccount \
     --header 'Authorization: Bearer {{YOUR_TOKEN}}' \
     --header 'Content-Type: application/json' \
     --data-raw '{
           "pixKey": "pixKey"
  }
}'

❗️

FYI

This operation is an asynchronous process and require some validations.

We will send a BENEFICIARY_BANK_ACCOUNT_VALIDATION notification to the integrator via webhook immediately after the account details validation (in this example, pixKey validation).

Read more about Webhook Notifications.

Callback Notification

As soon as the validation is completed, a callback is sent to the integrator URL:

{
  "operation": "BENEFICIARY_BANK_ACCOUNT_VALIDATION",
  "resourceId": null,
  "createdAt": "2024-04-10T15:48:30.036Z",
  "integratorId": "6616a6b9fdd060349d9556c7",
  "beneficiaryId": "6616a6befdd060349d9556c9",
  "message": "beneficiary pix validated.",
  "success": true,
  "data": {
    "id": "6616a6befdd060349d9556c9",
    "integratorId": "6616a6b9fdd060349d9556c7",
    "integratorBeneficiaryId": "ca488e8e-e65f-4b6d-9e36-876c115b439d",
    "type": "INDIVIDUAL",
    "person": {
     	...
      }
    },
    "business": null,
    "localTargetBankAccount": {
      "targetCountry": "BR",
      "accountDetails": {
        "isKeyValidated": true,
        "ispb": "00000000",
        "pixKey": "514fdd87-0940-4279-ba99-de53c56aa162"
      }
    },
    ...
  }
}

{
  "operation": "BENEFICIARY_BANK_ACCOUNT_VALIDATION",
  "resourceId": null,
  "createdAt": "2024-04-10T15:48:30.036Z",
  "integratorId": "6616a6b9fdd060349d9556c7",
  "beneficiaryId": "6616a6befdd060349d9556c9",
  "message": "beneficiary document number and pix key ownership mismatch",
  "success": false,
  "data": null
}

{
  "operation": "BENEFICIARY_BANK_ACCOUNT_VALIDATION",
  "resourceId": null,
  "createdAt": "2024-04-10T15:48:30.036Z",
  "integratorId": "6616a6b9fdd060349d9556c7",
  "beneficiaryId": "6616a6befdd060349d9556c9",
  "message": "beneficiary pix not found.",
  "success": false,
  "data": null
}

Retrieve local target account details for a beneficiary

curl --request GET \
     --url https://sandbox.api.caliza.co/core-api/v1/beneficiaries/{beneficiaryId}/localTargetAccount \
     --header 'Authorization: Bearer {{YOUR_TOKEN}}' \
     --header 'Content-Type: application/json'
}'

The data that is returned will vary based on the country of the beneficiary's target account.

Brazil (Pix)

{
  "targetCountry": "BR",
  "pixKey": "XXXXXXXXXXX",
  "ispb": "00000000"
}