Additional Sender Data and Document Upload
This guide outlines the process for providing additional underlying sender data during exchange order creation and for uploading supporting documents, which can then be attached to your transactions.
Sender Information Structure
When creating an exchange order, you can now pass detailed information about the underlying sender. This data is crucial for compliance and screening obligations.
Sender Information Structure
The sender object can represent either a company (business) or an individual.
A. For a Company (Business) Sender
If the sender is a business, use the following structure within your exchange order creation request:
Sample is below:
"sender": {
"country": "NG",
"type": "company",
"name": "Suit Country",
"customerIdentificationNumber": "45jtjy",
"accountNumber": "1234567890",
"address_line_1": "house street",
"address_line_2": "house street",
"address_city": "London",
"origination_country": "US",
"zip_code": "83888",
"registration_country": "NG",
"companyRegistrationNumber": "7575788",
"sub_category": "Baby products"
}
Field Name | Description | Comment | Mandatory/Optional |
|---|---|---|---|
country | Country of the origin of funds (origination country) | Mandatory | |
type | The type of underlying sender. individual or company | For corporates | Mandatory |
name | The name of the underlying sender | For corporate use cases, this must be the legal registered name | Mandatory |
customerIdentificationNumber | The customer identification number on your system | Either customerIdentificationNumber or accountNumber | |
accountNumber | The customer account number on your system | Either customerIdentificationNumber or accountNumber | |
address Line 1 | Complete sender address line (street, house number, building, apartment number etc.) | Mandatory | |
address Line 2 | Complete sender address line (street, house number, building, apartment number etc.) | Mandatory | |
address_city | Underlying sender address city | Mandatory | |
origination_country | Country of transfer initiation | Mandatory | |
zipCode | Sender's business address ZIP code | Mandatory | |
registration_country | Sender's business country of registration | Mandatory | |
companyRegistrationNumber | Sender's business registration number | Conditional based on use case, check with your account manager. | |
sub-category | Sender industry | Conditional based on use case, check with your account manager. |
B. For an Individual Sender
"sender": {
"country": "NG",
"type": "individual",
"name": "John Suit",
"dob": "1990-03-15",
"customerIdentificationNumber": "45jtjy",
"accountNumber": "1234567890",
"address Line 1": "house street",
"address Line 2": "house street",
"nationality": "NG",
"address_city": "London",
"origination_country": "US",
"zipCode": "83888"
}| Field Name | Description | Comment | Mandatory/Optional |
|---|---|---|---|
| country | Registered country of the clients address | Mandatory | |
| type | The type of underlying sender. individual or company | individual | Mandatory |
| name | The name of the underlying sender | For corporate use cases, this must be the legal registered name | Mandatory |
| dob | The date of birth of the sender | Mandatory | |
| customerIdentificationNumber | The customer identification number on your system | Either customerIdentificationNumber or accountNumber | |
| accountNumber | The customer account number on your system | Either customerIdentificationNumber or accountNumber | |
| address Line 1 | Complete sender address line (street, house number, building, apartment number etc.) | Mandatory | |
| address Line 2 | Complete sender address line (street, house number, building, apartment number etc.) | Mandatory | |
| address_city | Underlying sender address city | Mandatory | |
| origination_country | Country of transfer initiation | Mandatory | |
| zipCode | Sender's business address ZIP code | Mandatory | |
| nationality | Sender’s nationality | Mandatory |
Supporting Document Upload
Uploading a supporting document involves a three-step process:
- Generate an upload link.
- Upload the document to the generated link.
- Pass the uploaded document's unique key during transaction creation.
Step 1: Generating an Upload Link
To begin, you need to request a unique pre-signed link to upload your document.
Request: POST /documents/generate-upload-link
{
"fileName": "name_of_your_file.pdf"
}
Field Description:
| Field | Description |
|---|---|
| fileName | The name of the document, including its extension (e.g., Payment_receipt.png). |
Response:
A successful response will provide a link for uploading and a key that identifies your document.
{
"link": "https://your-upload-link.s3.amazonaws.com/...", // pre-signed link valid for 10 minutes
"key": "unique-s3-key-for-your-document" // supportingS3Key
}Response Field Descriptions:
| Field | Description | Comments |
|---|---|---|
| link | The pre-signed upload link for your document, valid for 10 minutes. | |
| key | A unique identifier (supportingS3Key) for your document. This key must be included when creating a payment to associate the document. | This key will be used in subsequent transaction creation requests to link the uploaded document. |
Step 2: Uploading the Document to the Upload Link
Once you have the upload link, you can perform a PUT request to upload your document. The request body should contain the document itself.
Request: PUT /link (where link is the URL obtained from Step 1)
// Example of the request body (the document binary data would be sent here)
{ "link": "supporting document" } // This indicates the content of the file.
A 200 OK response indicates a successful upload.
Step 3: Passing the Uploaded Document During Transaction Creation
After successfully uploading your document, you can associate it with a transaction by including the supportingDocS3Key in your payment creation request.
A. For "Make Conversion and Payout" Transactions (e.g., convertWalletPayout)
Include the supportingDocS3Key obtained from Step 1 in your request. Note that purposeId becomes mandatory if you attach a file.
{
"paymentType": "convertWalletPayout",
"sourceWalletId": 3529,
"sourceAmount": 5,
"purposeId": 14, // mandatory if attaching a file
"vfxToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"customPaymentReference": "9dc2ee8a15cd44e5",
"targetAccountId": 3786,
"paymentId": "9dc2ee8a-15cd-44e5-8ba8-b757c7a3b141",
"supportingDocS3Key": "unique-s3-key-for-your-document", // Key obtained in Step 1
"sender": {
// ... sender details as described in Section 1 ...
}B. For "Create a Payment Request (v2.2)" Transactions
Similarly, for Create a Payment Request (v2.2), include the supportingDocS3Key.
{
"beneficiaryId": 278,
"purposeId": 12,
"amount": 100,
"walletId": 1,
"clientReference": "Testing",
"paymentId": "a7600e0e-a973-4d26-b15c-89de5836e900",
"supportingDocS3Key": "unique-s3-key-for-your-document" // Key obtained in Step 1
}Response for Transaction Creation (with supportingDocS3Key):
The response for transaction creation will now include an additional field supportingDocument, which will contain a pre-signed downloadable link to view your uploaded file.
{
// ... existing response fields ...
"supportingDocument": "https://your-download-link.s3.amazonaws.com/..." // Pre-signed downloadable link
}Updated 6 months ago