International Remittance Payments
Guide on using the Remittances API for international money transfers via the Bitcoin Lightning Network
Bakkt revolutionizes international remittance payments by harnessing the speed of crypto rails for international fiat-to-fiat transfers, offering a significant advantage in cost and time efficiency when compared to the traditional banking system and forex conversions. Users can send international fiat transactions in just a few milliseconds via the Bitcoin lightning network. The lightning network is a scaling solution that provides a second layer operating on top of the Bitcoin blockchain that enables increased transaction speed among participating nodes. Bakkt utilizes the lightning network as the backend infrastructure for international fiat remittance payments.
Core Concepts and Functionality
On the front end, the user experience is simple. A US customer can seamlessly send USD to their mother in Mexico via the client’s platform, which then gets converted into Pesos for local pickup at her corner store in Mexico. Customers and clients will see fiat transactions in reports, as cryptocurrency operations occur only at Bakkt.
On the backend, when the user hits send, Bakkt buys Bitcoin and utilizes a Lightning Node Service Provider to facilitate this transaction. The lightening service provider then collaborates with a receiving operator to facilitate this remittance's output at a local financial service point. Bakkt will buy Bitcoin for transactions via the lightning network, clients are not involved in cryptocurrency handling.
Fees
Fees are explicitly detailed to the sender at the time of transaction initiation, which is valid until the estimate's expiration and currently calculated by the Estimate Endpoint as a percentage of the remittance amount. For example: Sending $100 plus $2 fee will amount to $102 that the customer will pay.
Reports
Clients can refer to the Cash Activity Report to view Remittance Payments reports and reconcile transactions. There will be no activity for Bitcoin trades or transfers related to lightning transactions as this is handled behind the scenes, and the client is only utilizing fiat for Remittance Payments and foreign fiat currency will come out at the end. In the Cash Activity Report, the transactions will include fees and appear as one transaction.
Notification
Clients will notify customers about their Remittance Payments being sent via email and upload a copy to our AWS S3 Bucket.
Workflow
To integrate this service, clients can use the Remittances API to enable international money transfers, offering their users a seamless remittance payment experience. This API is structured around two primary endpoints that serve distinct functions in the remittance process:
- Estimate Endpoint: This endpoint is designed to calculate the remittance cost. It provides clients with the expected transfer fees and the total amount required for the transaction. The output includes a preview of the exchange rate and includes a reference ID (estimateId) which is then used in the 'send' endpoint to complete the transaction. This estimate will have a different exchange rate and expiration time (between 1-5 minutes) depending on the receiving address.
- Send Endpoint: Utilized for executing the actual money transfer. This step requires input consistent with the 'estimate' phase, including the estimate ID and the total amount to be sent. The response from this endpoint will indicate the status of the transaction, such as 'success' or 'failure'.
Lightning Address Formats
For remittance payments, we accommodate both Lightning Addresses and Universal Money Addresses (UMA). Lightning Addresses are akin to email addresses and enable fund transfers directly. For instance, a typical Lightning Address might look like [email protected]. On the other hand, UMAs start with a dollar sign ($) such as $[email protected], and cater to a broader spectrum of cryptocurrency transactions. It's essential to use approved domains for these transactions. Please reach out to us for a list of supported domains to ensure smooth payment processing.
Currently, only outgoing fiat-to-fiat remittances for international transfers are supported for a select number of countries. We plan to expand our offerings to include incoming transactions in the near future.
Estimate
The Estimate endpoint calculates the expected cost of a remittance. It returns a detailed breakdown of the fees and the total amount, along with a reference ID (estimateId). This estimateId is necessary for linking the estimate to the send action. It's important to note that each estimate has an expiration time, and the send action should be completed within this period to ensure the accuracy of the quoted amount.
Estimate Request Fields
Field | Description |
---|---|
account | The account ID of the user initiating the payment. |
expectedReceiverCurrency | The currency that the receiver is expected to receive. |
senderCurrency | The currency in which the sender will make the payment. |
senderQuantity | The amount in the sender currency that the client wishes to estimate for the cost. |
receiverAddress | The lightning address or UMA of the receiver. |
Estimate Response Fields:
Field | Description |
---|---|
paymentEstimateId | Unique ID for the payment estimate. |
feeQuantity | The fee amount in the sender's currency. |
senderTotalQuantity | The total amount the sender will pay, including fees. |
receiverCurrency | The currency that the receiver will receive. |
receiverQuantity | The amount the receiver is expected to get (in the receiver currency). |
exchangeRate | The exchange rate from the sender's to the receiver's currency, excluding fees. |
exchangeRateIncludingFees | The effective exchange rate after fees. |
feePercentage | The percentage fee charged for the transaction. |
estimatedAt | The timestamp when the estimate was generated. |
expiresAt | The timestamp when the estimate expires. |
request | A copy of the original request. |
Example request/response
curl --location 'https://apex-crypto/api/v2/payments/send/estimate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <your_jwt_here>' \
--data-raw '{
"account": "0eacf91e-2d80-4718-b55e-50641cf0731a",
"expectedReceiverCurrency": "GTQ",
"senderCurrency": "USD",
"senderQuantity": "100.00",
"receiverAddress": "[email protected]"
}'
{
"paymentEstimateId": "7f04848b-4b52-4456-b254-ad2a11f98316",
"feeQuantity": "2.00",
"senderTotalQuantity": "102.00",
"receiverCurrency": "GTQ",
"receiverQuantity": "782.33",
"exchangeRate": "7.823346",
"exchangeRateIncludingFees": "7.669947",
"feePercentage": "2",
"estimatedAt": "2024-01-19T16:29:30.857779117Z",
"expiresAt": "2024-01-19T16:34:30.858032047Z",
"request": {
"account": "0eacf91e-2d80-4718-b55e-50641cf0731a",
"expectedReceiverCurrency": "GTQ",
"senderCurrency": "USD",
"senderQuantity": "100.00",
"receiverAddress": "[email protected]"
}
}
Send
Following the generation of an estimate, the 'send' endpoint is used to execute the transfer. Inputs for this step must match the response from the estimate step, including the estimate ID and the total send amount, which includes the fees. The endpoint's response indicates the success status of the transfer.
Send Request Fields
Field | Description |
---|---|
account | The account ID of the user initiating the payment. |
clientTransactionId | A unique identifier for the client's transaction. |
paymentEstimateId | The ID of the payment estimate obtained from the estimate step. |
description | An optional description for the payment. |
receiverCurrency | The currency the receiver will receive. |
senderCurrency | The currency in which the sender will make the payment. |
senderTotalQuantity | The total amount the sender will pay, including fees, in the sender currency. |
receiverAddress | The lightning address or UMA of the receiver. |
Send Response Fields
Field | Description |
---|---|
account | The account ID of the user initiating the payment. |
clientTransactionId | A unique identifier for the client's transaction. |
createdAt | The timestamp when the transaction was created. |
description | An optional description for the payment. |
exchangeRate | The exchange rate from the sender's to the receiver's currency. |
receiverCurrency | The currency received by the recipient. |
receiverQuantity | The amount received by the recipient. |
paymentEstimateId | The ID of the payment estimate used for this transaction. |
receivingAddress | The address to which the payment was sent. |
senderCurrency | The currency used by the sender for the transaction. |
senderFee | The fee amount charged from the sender. |
senderTotalQuantity | The total amount sent by the sender, including fees. |
status | The status of the transaction ('SUCCESS', 'FAILED'). |
transactionId | A unique identifier for the transaction. |
updatedAt | The timestamp when the transaction was last updated. |
request | A copy of the original request. |
Example request/response
curl --location 'https://apex-crypto/api/v2/payments/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <your_jwt_here>' \
--data-raw '{
"receiverAddress": "[email protected]",
"senderCurrency": "USD",
"receiverCurrency": "GTQ",
"paymentEstimateId": "7f04848b-4b52-4456-b254-ad2a11f98316",
"description": "Optional payment description",
"senderTotalQuantity": "102.00",
"clientTransactionId": "client_defined_transaction_id",
"account": "0eacf91e-2d80-4718-b55e-50641cf0731a"
}'
{
"account": "0eacf91e-2d80-4718-b55e-50641cf0731a",
"clientTransactionId": "client_defined_transaction_id",
"createdAt": "2024-01-19T17:22:05.429668349Z",
"description": "Optional payment description",
"exchangeRate": "7.823346",
"receiverCurrency": "GTQ",
"receiverQuantity": "782.33",
"paymentEstimateId": "9420dc78-dcec-4a23-92d9-40ea52d746d3",
"receivingAddress": "[email protected]",
"senderCurrency": "USD",
"senderFee": "2.00",
"senderTotalQuantity": "102.00",
"status": "success",
"transactionId": "884673db-3f19-48c0-b7de-f00e7db89bb4",
"updatedAt": "2024-01-19T17:22:08.974047636Z",
"request": {
"account": "0eacf91e-2d80-4718-b55e-50641cf0731a",
"clientTransactionId": "client_defined_transaction_id",
"paymentEstimateId": "7f04848b-4b52-4456-b254-ad2a11f98316",
"description": "Optional payment description",
"receiverCurrency": "GTQ",
"senderCurrency": "USD",
"senderTotalQuantity": "102.00",
"receiverAddress": "[email protected]"
}
}
Updated 6 months ago