Wallet to wallet Confirm Swap
POST {{base_url}}/api/v1/user/wallet/swap/confirm
Confirms an initialized internal wallet swap using the user's wallet PIN.
This endpoint completes the authorization step for a swap that was previously initialized through the Internal Swap endpoint.
The auth_token required by this endpoint is generated and returned by the initial swap request:
POST {{base_url}}/api/v1/user/wallet/swap
The merchant must pass the returned auth_token to this endpoint together with the user's wallet PIN.
How It Works
The internal swap follows a two-step process:
1. Initialize Swap
POST /api/v1/user/wallet/swap
↓
LedgerBlock returns auth_token
↓
2. Confirm Swap
POST /api/v1/user/wallet/swap/confirm
↓
Submit auth_token + wallet_pin
↓
Swap confirmed and initiatedImportant: The
auth_tokenmust come from the response of the initial swap request. It should not be generated by the merchant.
Request
Headers
Use the standard LedgerBlock authentication headers.
Content-Type: application/json
Authorization: Bearer {{secret_key}}Request Body
{
"user_ref": "{{vault:Merchant-user-ref}}",
"auth_token": "ba5cf11ea9cdc4037d1ed3224fa0b1a729d55c9db09d4eb4ebd8ec9c535b6fbb",
"wallet_pin": "787678"
}Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_ref | string | Yes | The merchant's reference for the user confirming the swap. |
auth_token | string | Yes | The authorization token returned when the internal swap was initialized. |
wallet_pin | string | Yes | The user's wallet PIN used to authorize the swap. |
Using the auth_token
auth_tokenWhen the merchant initializes a swap, LedgerBlock returns an auth_token in the response.
For example:
{
"status": "success",
"message": "Swap initialized. Confirm with your wallet PIN to complete it",
"data": {
"payment_ref": "dc843631-87ac-45ad-b438-d6d732882eea",
"txn_ref": "sw_000001",
"from_currency": "CAD",
"to_currency": "NGN",
"amount": 1,
"converted_amount": 972,
"rate_used": 972,
"auth_token": "a4cd4dcefeb436a538e56f1a8d8b63d778d1c43b89cf065244bdddf1a068aeb5",
"expires_in_seconds": 600
}
}The merchant then uses that auth_token when calling the confirmation endpoint:
{
"user_ref": "{{vault:Merchant-user-ref}}",
"auth_token": "a4cd4dcefeb436a538e56f1a8d8b63d778d1c43b89cf065244bdddf1a068aeb5",
"wallet_pin": "787678"
}The token is therefore the link between the swap initialization and swap confirmation requests.
Successful Response
{
"status": "success",
"message": "Swap confirmed and initiated successfully"
}Response Parameters
| Parameter | Type | Description |
|---|---|---|
status | string | Indicates whether the confirmation request was successful. |
message | string | Describes the result of the confirmation request. |
Complete Internal Swap Flow
The complete process is:
Step 1 — Initialize the Swap
The merchant specifies the source wallet, destination currency, amount, transaction reference, and notification URL.
POST /api/v1/user/wallet/swapLedgerBlock validates the request and returns an auth_token.
Step 2 — Confirm the Swap
The merchant submits:
user_refauth_tokenreturned from Step 1- User's
wallet_pin
POST /api/v1/user/wallet/swap/confirmStep 3 — Swap Initiated
After successful PIN confirmation, LedgerBlock confirms and initiates the swap.
Swap confirmed and initiated successfullyThe transaction can then proceed through LedgerBlock's processing and notification flow.
Updated 2 months ago
