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 initiated

Important: The auth_token must 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`

When 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/swap

LedgerBlock validates the request and returns an auth_token.

Step 2 — Confirm the Swap

The merchant submits:

user_ref
auth_token returned from Step 1
User's wallet_pin

POST /api/v1/user/wallet/swap/confirm

Step 3 — Swap Initiated

After successful PIN confirmation, LedgerBlock confirms and initiates the swap.

Swap confirmed and initiated successfully

The transaction can then proceed through LedgerBlock's processing and notification flow.