Guides
Guides
Guides

Wire payment-out

Allow Beneficiaries to initiate an electronic funds transfer from their Caliza wallet.

Suggest Edits

Overview

Payment out is a movement of funds from a beneficiary's Caliza wallet to a US-based account via wire transfer

Core concepts

  • Payment Contact: These must include the destination bank account and accountholder information. Before creating a simulation, we must first create a payment contact.
  • Payment Simulation: It is the process of obtaining the approximate amount of fees for a given transaction.
  • Payment Confirmation: It is the process of executing a simulation

❗️

Notice

The fee can be changed between the simulation process and the payment process. The fee is not a guaranteed amount, it is just an estimate.

Creating payment contact

The first step to creating a payment out is defining a payment contact. The payment contact is the target account to which the funds will be delivered. The payment contact ID will be required in order to execute the payment. More details on the payment contact creation are available here: Creating Payment Contact

Simulating payment (View API reference)

The first step is to create a payment simulation, which returns the indicative amount of funds to be received at the end of the payment and generates a simulationId required to launch the transaction.

  • Call POST /v1/payments/simulations to create a payment simulation
  • Based on the latest exchange rate, we calculate and return the likely amount (in USD) to be received by the target bank account

Example request to create a payment simulation:

curl --location --request POST 'https://sandbox.api.caliza.co/core-api/v1/payments/simulations' \
--header 'Authorization: Bearer {YOUR_BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
     "beneficiaryId": "64af1510267758301e2c6c7f",
     "amount": 50.0
}'

The response to the request above is:

{
    "id": "ee1c3f3a-5823-4627-af93-559e54a1b225",
    "integratorId": "64a77197e459bc78b6585fa7",
    "beneficiaryId": "64af1510267758301e2c6c7f",
    "amount": {
        "currencyCode": "USDC",
        "value": "50.00"
    },
    "amountAfterFee": {
        "currencyCode": "USD",
        "value": "45.00"
    },
    "transactionDetails": {
        "taxes": {
            "currencyCode": "USD",
            "value": "0.00"
        },
        "feeDetails": {
            "totalFees": {
                "currencyCode": "USD",
                "value": "5.00"
            },
            "integratorFee": {
                "currencyCode": "USD",
                "value": "0.00"
            }
        }
    },
    "executed": false
}

Executing payment (View API reference)

After simulating a payment, it's time to create it for real. The only thing you need to send is the simulationId, which we generated in the previous step, the paymentContactId and a description. This request will generate an id associated with the payment, which you can use to check its status. We'll send callbacks as the status changes.

  • Call POST /v1/payments with the simulationId, paymentContactId and description
  • Now we create your payment based on your previous simulation, which will be executed at the latest exchange rate

Example request to create a payment:

curl --location --request POST 'https://sandbox.api.caliza.co/core-api/v1/payments' \
--header 'Authorization: Bearer {YOUR_BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
     "simulationId": "630bdaeee5f4450249fffb34",
     "paymentContactId": "62a9f7752f3bcf4f32a4e2c7",
     "description": "Testing payment"
}'

The response to the above call should be:

{
	"id": "630bdb34e5f4450249fffb35",
	"simulationId": "630bdaeee5f4450249fffb34",
	"integratorId": "6306548828912548710e667c",
	"beneficiaryId": "6306556b28912548710e667e",
	"amount": {
    "currencyCode": "USDC",
    "value": "50.00"
  },
  "amountAfterFee": {
    "currencyCode": "USD",
    "value": "45.00"
  },
  "transactionDetails": {
    "taxes": {
      "currencyCode": "USD",
      "value": "0.00"
    },
    "feeDetails": {
      "totalFees": {
        "currencyCode": "USD",
        "value": "5.00"
      },
      "integratorFee": {
        "currencyCode": "USD",
        "value": "0.00"
      }
    }
  },
    "executed": false,
	"type": "WIRE",
	"status": "PENDING",
	"paymentContactId": "630661410d13dd4960c7e5bc",
	"description": "aaaaaa",
	"createdDate": "2022-08-28T21:16:36.913791Z",
	"lastModifiedDate": "2022-08-28T21:16:36.913791Z"
}

❗️

Notice

  • All payment transactions are in USD
  • The payment has four status:
    PENDING: Payment will be started, it is the status right before creation
     SUCCEEDED: Payment was executed with success
    FAILED: Something went wrong during the payment process
     CANCELLED: Payment was cancelled by the user during the execution
  • The expected fee should be different after the end of the payment processing, expectedFeeAmount is just an estimate

Checking the progress of payment (View API reference)

Call GET /v1/payments/{id} to check the status of your payment.

Possible status responses are: PENDING, SUCCEEDED, FAILED, and CANCELLED.

curl --request GET \
     --url https://sandbox.api.caliza.co/core-api/v1/payments/{id} \
     --header 'Authorization: Bearer {{YOUR_TOKEN}}' \

❗️

Notice

We take several internal steps before marking a payment as succeeded, and the complete payload will only be available once the status is succeeded. Before then, it's possible to receive a response without the feeDetails and amountAfterFee fields.

Callback notification

As soon as a new payment is completed, a callback is sent to the integrator URL

{
	"operation": "PAYMENT_OUT",
  "resourceId": "6306548828912548710e667c",
  "createdAt": "2022-08-02T15:51:49.119+00:00",
  "integratorId": "6306548828912548710e665a",
  "beneficiaryId": "6306548828912548710e667a",
  "success": false,
  "message": "Beneficiary doesn't have enough funds"
}

{
	"operation": "PAYMENT_OUT",
	"resourceId": "632a2018806bd7009719735c",
	"createdAt": "2022-09-20T17:18:32.877678",
	"integratorId": "6306548828912548710e667c",
	"beneficiaryId": "6306556b28912548710e667e",
	"message": null,
	"success": true,
	"data": {
		"id": "632a2018806bd7009719735c",
		"simulationId": "632a2012806bd7009719735b",
		"integratorId": "6306548828912548710e667c",
		"beneficiaryId": "6306556b28912548710e667e",
		"amount": {
			"currencyId": "6227f5d27f58553906108dab",
			"currencyCode": "USDC",
			"value": 100
		},
		"amountAfterFee": {
			"currencyId": "6227f5d27f58553906108dab",
			"currencyCode": "USDC",
			"value": 88
		},
		"type": "WIRE_OUT",
		"status": "SUCCEEDED",
		"paymentContactId": "6328d636616c1e7beb8652b2"
	}
}

Updated 9 months ago