Changelog

Customer Deposit Webhook Update

by Taiwo Odetola

The deposit webhook for virtual accounts has been updated to include a new field: depositor_details. This field provides detailed information about the depositor when available.

Details of the Change

New Field Added: depositor_details has been added to the data object within the deposit webhook payload.

Field Description:
depositor_details: An object containing details about the depositor, including the name, SWIFT code, sort code, bank name, account number, and IBAN.
If the depositor's details are not available, the depositor_details field will be set to null

Example

Example of the depositor details when populated

{
  "name": "John Doe",
  "swift_code": "SWIFT1234",
  "sort_code": "",
  "bank_name": "",
  "account_number": "",
  "iban": "GB82WEST12345698765432"
}

Before the change

{
   "id": "e64488ba-906b-4717-9e33-cd18fa5c8f8b",
   "event": "payment",
   "resource_type": "deposit",
   "data": {
    "id": "123456",
    "customer_id": "923b2df5-4a89-4ceb-b148-c2e5ac52d04e",
    "business_id": "bfa03a8b-7963-432c-870d-1615e1ade10f",
    "reference": "842ccb30-2b7b-437e-b991-e1320c3b0fb9",
    "currency": "USD",
    "amount": 1000.50,
    "deposited_amount": 1000.50,
    "deposited_currency": "USD",
    "channel": "bank_transfer",
    "depositor_details": null,
    "created_at": "2024-05-22T14:48:00Z",
    "status": "completed"
   },
   "live": false,
   "timestamp": 1713521972
}

After the change

{
   "id": "e64488ba-906b-4717-9e33-cd18fa5c8f8b",
   "event": "payment",
   "resource_type": "deposit",
   "data": {
    "id": "123456",
    "customer_id": "923b2df5-4a89-4ceb-b148-c2e5ac52d04e",
    "business_id": "bfa03a8b-7963-432c-870d-1615e1ade10f",
    "reference": "842ccb30-2b7b-437e-b991-e1320c3b0fb9",
    "currency": "GBP",
    "amount": 1000.50,
    "deposited_amount": 1000.50,
    "deposited_currency": "GBP",
    "channel": "bank_transfer",
    "depositor_details": {
   		 "name": "John Doe",
   		 "swift_code": "SWIFT1234",
   		 "sort_code": "",
   		 "bank_name": "",
   		 "account_number": "",
   		 "iban": "GB82WEST12345698765432"
		},
    "created_at": "2024-05-22T14:48:00Z",
    "status": "completed"
   },
   "live": false,
   "timestamp": 1713521972
}

{
   "id": "e64488ba-906b-4717-9e33-cd18fa5c8f8b",
   "event": "payment",
   "resource_type": "deposit",
   "data": {
    "id": "123456",
    "customer_id": "923b2df5-4a89-4ceb-b148-c2e5ac52d04e",
    "business_id": "bfa03a8b-7963-432c-870d-1615e1ade10f",
    "reference": "842ccb30-2b7b-437e-b991-e1320c3b0fb9",
    "currency": "GBP",
    "amount": 1000.50,
    "deposited_amount": 1000.50,
    "deposited_currency": "GBP",
    "channel": "bank_transfer",
    "depositor_details": null,
    "created_at": "2024-05-22T14:48:00Z",
    "status": "completed"
   },
   "live": false,
   "timestamp": 1713521972
}

Impact

Backward Compatibility: This change is backward-compatible. The depositor_details field will appear as null for deposits where this information is not available, ensuring no disruptions to existing integrations.
Usage: Developers should update their integrations to handle the new depositor_details field, especially if they require information about the depositor for further processing or logging.

Action Required

Review and update your webhook handling code to process the new depositor_details field if required.
Test your integration to ensure it handles both scenarios where depositor_details is populated and when it is null.

Quote ID addition

by Mariam AbdulGaniyu

This document describes the updates to our APIs to address the potential issue of rate changes between fetching a rate/quote and initiating a transfer or currency swap. We have implemented the use of a quoteID to lock rates for a specified duration within which the locked rates can be used.

A. Fetch Rates/Quotes API
Endpoint: GET /api/v1/quotes
Description: Fetches the current exchange rates and returns alongside a quoteID to lock the rate for a specified duration.
Sample Response

{  
    "status": 200,  
    "data": {  
        "exchange_rate": 1600,  
        "fee_percentage": 10,  
        "flat_fee": 0,  
        "fee_amount": 100000,  
        "amount_receivable": 562.5,  
        "quote_id": "9b532b81-8f3b-40cf-8fe3-816a59548757",  
        "quote_expiry_in_minutes": "10m0s"  
    },  
    "message": "Retrieved exchange rates successfully",  
    "error": null  
}

B. Initiate Currency Swap API
Endpoint: POST /api/v1/initiateCurrencySwap
Description: Initiates a currency swap. Optionally accepts a quoteID to use a previously locked rate.

Request Body:
quoteID (optional): The quoteID received from the fetch rates/quotes API.

Response Body:Same as before

C. Initiate Transfer API
Endpoint: POST /api/v1/transfers
Description: Initiates a transfer. Optionally accepts a quoteID to use a previously locked rate.
Request Body:

{  
    "amount": 212,  
    "source_currency": "USD",  
    "destination_currency": "NGN",  
    "use_balance": "no",  
    "destination": {  
        "type": "fiat",  
        "bank_details": {  
            "account_name": "Olawale OLADAPO",  
            "account_number": "201148503",  
            "bank_address": "1, God's Own Avenue, Lagos",  
            "bank_branch": "",  
            "bank_code": "058",  
            "bank_name": "First Bank",  
            "city": "God's Own",  
            "country": "NG",  
            "district": "",  
            "is_mobile_money": "no",  
            "is_within_us": "no",  
            "postal_code": "",  
            "routing_number": "",  
            "swift_code": "FBNINGLA"  
        },  
        "personal_details": {  
            "name": "Olawale OLADAPO",  
            "address": "Olawale Avenue",  
            "city": "Lagos",  
            "country": "NG",  
            "district": "",  
            "email": "",  
            "postal_code": "",  
            "phone_number": ""  
        }  
    },  
    "quote_id": "9b532b81-8f3b-40cf-8fe3-816a59548757",  
    "note": "this is the first note here",  
    "reason": "some reason for the transfer"  
}

Transaction Reference added to payout payload

by Mariam AbdulGaniyu

An optional fieldtransaction_referencehas been added to the initiate direct payout payload to allow businesses identify duplicate transactions for a payout.

{
    "currency": "NGN",
    "remarks": "00020",
    "transaction_reference": "4de1d015-d909-4f83-ad2c-c5cf7b16ef14",
    "accounts": [
        {
            "amount": 120000,
            "remarks": "TM-bcfc37778ba4",
            "destination": {
                "bank_details": {
                    "account_name": "SABI KETU",
                    "account_number": "90254323333",
                    "bank_code": "304"
                }
            }
        }
    ],
    "beneficiary_type": "single"
}

Endpoint update for mock deposit into virtual accounts

by Mariam AbdulGaniyu

The mock deposit endpoint has been updated from {{base_url}}/api/v1/payments/mock and changed to {{base_url}}/api/v1/payments/mocks/customer-deposit

Payload remains the same. Example:

{
    "customer_id": "3a73d3c1-79f3-457d-ad88-5ce3089197174",
    "currency": "GBP",
    "amount": 400000
}

Expiration Date for Bank Accounts (EUR & GBP)

by Taiwo Odetola

We have introduced a new field expiration_date to the payload for creating bank accounts (only EUR and GBP). This change is part of our ongoing efforts to enhance the security and functionality of our banking API.

Endpoint:

POST /payments/banks/account

New Field:

expiration_date (string, required): The expiration date of the document provided. This field must be at least one month away from the current date. The date should be in the format YYYY-MM-DD.


Updated Payload Example:

{
    "customer_id": "6a2e2ef4-d120-40de-8556-f66d70d38b2e",
    "currency": "GBP",
    "phone_number": "2348109023376",
    "reference": "6a2e2ef4-d120-40de-8556-f66d70d38b2e",
    "document_type": "passport",
    "document_number": "A334453332",
    "issued_country_code": "NG",
    "issued_by": "Ministry of Interior",
    "issued_date": "2010-09-09",
    "expiration_date": "2024-07-04",
    "country": "NG",
    "zip_code": "73301",
    "street": "Lagos",
    "state": "Lagos",
    "date_of_birth": "2000-09-09"
}