payment

PAYMENT

A. PAYMENT WITH VOUCHER

Fetch Voucher Redemption Charges

POST /merchant-integrations/fetch-voucher-redemption-charges

Get the charges associated with redeeming a voucher.

Request Body

{
  "amount": 0,
  "lockPin": "string",
  "voucherCode": "string"
}

lockPin is optional and needed in cases where a user decides to add extra security to his voucher by locking it with a 4 digit pin.

Every voucher can be redeemed in bids, hence the required field for amount

Response

{
  "message": "string",
  "code": "number",
  "status": "string",
  "data": {
    "charges": {
      "swapAmount": "number",
      "toAmount": "number",
      "processingFee": "number",
      "totalGasAndProceesingFeeInFromCurrency": "number",
      "totalGasCostAndProcessingFeeInWei": "number",
      "exchangeRate": "number",
      "percentageCharge": "number",
      "isPercentageCharge": "boolean",
      "toCurrency": {
        "id": "string",
        "image": "string",
        "name": "string",
        "symbol": "string",
        "Abbreviation": "string",
        "currencyType": "string",
        "isActive": "boolean",
        "createdAt": "string"  // ISO 8601 timestamp
      },
      "fromCurrency": {
        "id": "string",
        "image": "string",
        "name": "string",
        "symbol": "string",
        "Abbreviation": "string",
        "currencyType": "string",
        "isActive": "boolean",
        "createdAt": "string"  // ISO 8601 timestamp
      },
      "totalDeductable": "number"
    },
    "voucher": {
      "id": "string",
      "amount": "number",
      "balance": "number",
      "generatedCurrency": {
        "id": "string",
        "image": "string",
        "name": "string",
        "symbol": "string",
        "Abbreviation": "string",
        "currencyType": "string",
        "isActive": "boolean",
        "createdAt": "string"  // ISO 8601 timestamp
      },
      "code": "string",
      "wasPaidFor": "boolean",
      "isUsed": "boolean",
      "createdAt": "string",  // ISO 8601 timestamp
      "createdForMerchant": "boolean",
      "createdForExistingUser": "boolean",
      "createdForNonExistingUser": "boolean",
      "isLocked": "boolean",
      "onchain": "boolean",
      "onchainProcessing": "boolean",
      "cryptoVoucherDetails": "null",
      "transactionHash": "string",
      "metaData": "string"
    }
  }
}

Redeem Voucher

POST /merchant-integrations/redeem-voucher

Redeem a voucher for a customer.

Request Body

{
  "amount": 0,
  "lockPin": "string",
  "voucherCode": "string"
}

Response

{
  "code": 0,
  "message": "string",
  "status": "string"
}

B. Payment via Longswipe app authorisation

1. Accept Longswipe identifier (email, username, phone number)

Confirm Existing User

GET /merchant-integrations/confirm-user/:identifier Bear Token: pk_test_abc123456

Use this endpoint to confirm existing lonswipe user using the identifier.

Response

{
  "message": "string",
  "code": 200,
  "status": "string",
  "data": {
    "fullName": "string",
    "email": "string",
    "phone": "string",
    "avatar": "string"
  }
}

Payment Request

POST /merchant-integrations/payment-request Bear Token: pk_test_abc123456

Use this endpoint to request payment.

Request Body

{
  "amount": "float",
  "currency": "string",
  "user_identifier": "string",
  "metadata": {
    "key1": {},
    "key2": {}
  },
  "reference_id": "string"
}

Response

{
  "message": "string",
  "code": 200,
  "status": "string"
}

C. Payment Via wallet address deposit

Address Deposit Request

POST /merchant-integrations/deposit-address-payment-request Bear Token: pk_test_abc123456

Request a blockchain deposit address.

Request Body

{
  "amount": "float",
  "blockchainNetworkId": "string",
  "currency_abbreviation": "string",
  "metadata": {
    "key1": {},
    "key2": {}
  },
  "pay_with_currency_abbreviation": "string",
  "reference_id": "string"
}

Response

{
  "message": "string",
  "code": 200,
  "status": "string",
  "data": {
    "id": "string",
    "address": "string",
    "amountToDeposit": "float",
    "expiresAt": "string (ISO date)",
    "dateCreated": "string (ISO date)",
    "blockchainNetworkDetail": {
      "id": "string",
      "networkName": "string",
      "chainID": "string",
      "blockExplorerUrl": "string (URL)",
      "networkType": "string",
      "networkLogo": "string (URL)"
    }
  }
}

Request Wallet Deposit Charges

POST /merchant-integrations/request-wallet-deposit-charges Bear Token: pk_test_abc123456

Request a blockchain wallet deposit charges.

Request Body

{
  "amount": "float",
  "blockchainNetworkId": "string",
  "currency_abbreviation": "string",
  "pay_with_currency_abbreviation": "string"
}

Response

{
  "message": "string",
  "code": 200,
  "status": "string",
  "data": {
    "swapAmount": "float",
    "toAmount": "float",
    "processingFee": "float",
    "totalGasAndProceesingFeeInFromCurrency": "float",
    "totalGasCostAndProcessingFeeInWei": "float",
    "exchangeRate": "float",
    "percentageCharge": "float",
    "isPercentageCharge": true,
    "toCurrency": {
      "id": "string",
      "image": "string (URL)",
      "name": "string",
      "symbol": "string",
      "Abbreviation": "string",
      "currencyType": "string",
      "isActive": true,
      "createdAt": "string (ISO date)"
    },
    "fromCurrency": {
      "id": "string",
      "image": "string (URL)",
      "name": "string",
      "symbol": "string",
      "Abbreviation": "string",
      "currencyType": "string",
      "isActive": true,
      "createdAt": "string (ISO date)"
    },
    "totalDeductable": "float"
  }
}

D. OPtional Endpoints

Verify Transaction

GET /merchant-integrations-server/verify-transaction/:referenceID Bear Token: pk_test_abc123456 X-API-Private-Key: sk_test_def7891011

Use this endpoint to verify the status of a transaction by its reference ID after a customer has completed a payment. This helps ensure that the transaction was successful and recorded correctly.

Transaction Status Codes

Status	Description
PENDING	Transaction is pending
PROCESSING	Transaction is being processed
APPROVED	Transaction is approved
CANCELED	Transaction is canceled
COMPLETED	Transaction is completed
FAILED	Payment failed or was declined
REFUNDED	Transaction has been refunded
REVERSED	Transaction has been reversed

Response

{
  "message": "string",
  "code": 200,
  "status": "string",
  "data": {
    "id": "string",
    "userId": "string or null",
    "referenceId": "string",
    "amount": "float",
    "title": "string",
    "message": "string",
    "chargedAmount": "float",
    "chargeType": "string",
    "type": "string",
    "status": "string",
    "currency": {
      "id": "string",
      "image": "string (URL)",
      "name": "string",
      "symbol": "string",
      "Abbreviation": "string",
      "currencyType": "string",
      "isActive": true,
      "createdAt": "string (ISO date)"
    },
    "createdAt": "string (ISO date)",
    "updatedAt": "string (ISO date)",
    "transactionHash": "string",
    "applicationName": "string",
    "referenceHash": "string",
    "metaData": "string"
  }
}

Verify Voucher

POST /merchant-integrations/verify-voucher

Verify the validity of a voucher before redemption.

It is optional and useful in cases where you need to show your users the status of a voucher before it is redeemed

Request Body

{
  "voucherCode": "string"
}

Response

{
  "message": "string",
  "status": "string",
  "code": 0,
  "data": {
    "amount": 0,
    "balance": 0,
    "code": "string",
    "createdAt": "string",
    "createdForExistingUser": true,
    "createdForMerchant": true,
    "createdForNonExistingUser": true,
    "cryptoVoucherDetails": {
      "balance": "string",
      "codeHash": "string",
      "creator": "string",
      "isRedeemed": true,
      "transactionHash": "string",
      "value": "string"
    },
    "generatedCurrency": {
      "abbrev": "string",
      "currencyType": "string",
      "id": "string",
      "image": "string",
      "isActive": true,
      "name": "string",
      "symbol": "string"
    },
    "id": "string",
    "isLocked": true,
    "isUsed": true,
    "metaData": "string",
    "onchain": true,
    "onchainProcessing": true,
    "redeemedVouchers": [
      {
        "amount": 0,
        "createdAt": "string",
        "id": "string",
        "isMerchant": true,
        "redeemedUserID": "string",
        "redeemerWalletAddress": "string",
        "user": {
          "avatar": "string",
          "email": "string",
          "emailVerified": true,
          "externalID": "string",
          "id": "string",
          "isActive": true,
          "isPinSet": true,
          "otherNames": "string",
          "phone": "string",
          "regChannel": "string",
          "role": "ADMIN",
          "surname": "string",
          "username": "string"
        },
        "voucherID": "string"
      }
    ],
    "transactionHash": "string",
    "wasPaidFor": true
  }
}