Remittance payments

Let’s take an example of a generic remittance payments provider to see how the Flagright API can be seamlessly used as the compliance and anti-fincrime infrastructure.

You can find the relevant case study here. If your organization also provides a wallet along with remittance payments, checkout the digital wallet use case.

Business Entities

Any business entity is represented as Business entity in the Flagright API. Everytime a new legal entity onboards to your system, you can create them at Flagright using the Create business API.

To make the following request, you’ll need an API Key. Please reach out if you don’t have one.

POST /business/users
$    curl -X POST https://sandbox.api.flagright.com/business/users \
>        -H "x-api-key: <apiKey>" \
>        -H "Content-Type: application/json" \
>        -d '{
>    "userId": "userId",
>    "createdTimestamp": 1.1,
>    "legalEntity": {
>        "companyGeneralDetails": {
>        "legalName": "Ozkan Hazelnut Export JSC",
>        "businessIndustry": [
>            "Farming"
>        ],
>        "mainProductsServicesSold": [
>                "Hazelnut"
>            ]
>        },
>        "companyFinancialDetails": {
>        "expectedTransactionAmountPerMonth": {
>            "amountValue": 800,
>            "amountCurrency": "GBP"
>        }
>        },
>        "companyRegistrationDetails": {
>        "registrationIdentifier": "PSJ554342",
>        "registrationCountry": "DE"
>        }
>    },
>    "shareHolders": [
>        {
>        "generalDetails": {
>            "name": {
>            "firstName": "Baran",
>            "middleName": "Realblood",
>            "lastName": "Ozkan"
>            },
>            "dateOfBirth": "1991-01-01",
>            "countryOfResidence": "US",
>            "countryOfNationality": "DE"
>        },
>        "contactDetails": {
>            "emailIds": [
>            "baran@flagright.com"
>            ],
>            "contactNumbers": [
>            "+371 123132"
>            ],
>            "websites": [
>            "flagright.com"
>            ],
>            "addresses": [
>            {
>                "addressLines": [
>                "Klara-Franke Str 20"
>                ],
>                "city": "Berlin",
>                "country": "Germany",
>                "postcode": "10557",
>                "state": "Berlin"
>            }
>            ]
>        }
>        }
>    ],
>    "directors": [
>        {
>        "generalDetails": {
>            "name": {
>            "firstName": "Baran",
>            "middleName": "Realblood",
>            "lastName": "Ozkan"
>            },
>            "dateOfBirth": "1991-01-01",
>            "countryOfResidence": "US",
>            "countryOfNationality": "DE"
>        },
>        "legalDocuments": [
>            {
>            "documentType": "passport",
>            "documentNumber": "Z9431P",
>            "documentIssuedCountry": "DE",
>            "documentIssuedDate": 1639939034000,
>            "documentExpirationDate": 1839939034000,
>            "tags": [
>                {
>                "key": "customerType",
>                "value": "wallet"
>                },
>                {
>                "key": "customKey",
>                "value": "customValue"
>                }
>            ],
>            "nameOnDocument": {
>                "firstName": "Baran",
>                "middleName": "Realblood",
>                "lastName": "Ozkan"
>            }
>            },
>            {
>            "documentType": "passport",
>            "documentNumber": "Z9431P",
>            "documentIssuedCountry": "DE",
>            "documentIssuedDate": 1639939034000,
>            "documentExpirationDate": 1839939034000,
>            "nameOnDocument": {
>                "firstName": "Baran",
>                "middleName": "Realblood",
>                "lastName": "Ozkan"
>            }
>            }
>        ]
>        }
>    ]
>
>}'

Users

Consumer users - individuals on either side of the transaction - are represented as Consumer entity in the Flagright API. You would make an API request to the POST /consumer/users endpoint to create a new consumer, with the payload like:

To make the following request, you’ll need an API Key. Please reach out if you don’t have one.

POST /consumer/users
$    curl -X POST https://sandbox.api.flagright.com/consumer/users \
>     -H "x-api-key: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "createdTimestamp": 1641654664000,
>  "userId": "96647cfd9e8fe66ee0f3362e011e34e8",
>  "contactDetails": {
>    "emailIds": [
>      "baran@flagright.com"
>    ],
>    "contactNumbers": [
>      "+37112345432"    ],
>    "websites": [
>      "flagright.com"
>    ],
>  },
>  "legalDocuments": [
>    {
>      "documentType": "passport",
>      "documentNumber": "Z9431P",
>      "documentIssuedCountry": "DE",
>      "documentIssuedDate": 1639939034000,
>      "documentExpirationDate": 1839939034000,
>      "nameOnDocument": {
>        "firstName": "Baran",
>        "middleName": "Realblood",
>        "lastName": "Ozkan"
>      }
>    }
>  ],
>  "userDetails": {
>    "name": {
>      "firstName": "Baran",
>      "middleName": "Realblood",
>      "lastName": "Ozkan"
>    },
>    "dateOfBirth": "1991-01-01",
>    "countryOfResidence": "US",
>    "countryOfNationality": "DE"
>  }
>}'

Transactions

For remittance payments, there are typically two out of the three types of transactions:

Money out of the country

Transferring money out of the country is overwhelmingly the primary type of transaction is when a user transfers money from home country to a payment instrument (typically a bank account) in another country.

The origin payment method is the payment instrument used to send the money. The destination payment method is the payment instrument used to receive the money (typically a bank account). In this case, the originUserId would be the user initiating the transaction.

The destinationUserId typically would be empty, since the user receiving the payment isn’t the customer of the remittance solution.

You would make an API call to the POST /transactions to verify this transaction before processing, with the payload like so:

To make the following request, you’ll need an API Key. Please reach out if you don’t have one.

You would make an API call to the POST /transactions to verify this transaction before processing, with the payload like:

POST /transactions
$    curl --request POST \
>    --url https://sandbox.api.flagright.com/transactions \
>    --header 'Content-Type: application/json' \
>    --data '{
>    "transactionId": "7b80a539eea6e78acbd6d458e5971482",
>    "type": "TRANSFER",
>    "originUserId": "9350a2611e0771cba03310f74bf6",
>    "originAmountDetails": {
>        "country": "NL",
>        "transactionAmount": 800,
>        "transactionCurrency": "EUR"
>    },
>    "destinationAmountDetails": {
>        "country": "IN",
>        "transactionAmount": 72331,
>        "transactionCurrency": "INR"
>    },
>    "timestamp": 1641654664,
>    "originPaymentDetails": {
>        "method": "IBAN",
>        "IBAN": "NL37RABO1954254121",
>        "BIC": "RABONL2U",
>        "bankName": "Rabobank"
>    },
>    "destinationPaymentDetails": {
>        "method": "GENERIC_BANK_ACCOUNT",
>        "accountNumber": "500105178535472592",
>        "bankCode": "SBIN0005622",
>        "bankName": "SBI"
>    }
>    }'

Money into the country

The other use case in money into the home country, where the remittance solution would allow a user to receive international payments. In this case, the originUserId typically would be empty, since the user sending the payment isn’t the customer of the remittance payment provider and the remittance provider typically does not have information on the user. If you perform KYC on the end user and have information on them, you can pass in the consumer userId as the originUserId.

The destinationUserId would be the userId of the user receiving the payment.

You would make an API call to the POST /transactions to verify this transaction before processing, with the payload like so:

To make the following request, you’ll need an API Key. Please reach out if you don’t have one.

You would make an API call to the POST /transactions to verify this transaction before processing, with the payload like:

POST /transactions
$    curl --request POST \
>    --url https://sandbox.api.flagright.com/transactions \
>    --header 'Content-Type: application/json' \
>    --data '{
>    "transactionId": "7b80a539eea6e78acbd6d458e5971482",
>    "type": "REFUND",
>    "destinationUserId": "9350a2611e0771cba03310f74bf6",
>    "originAmountDetails": {
>        "country": "IN",
>        "transactionAmount": 72331,
>        "transactionCurrency": "INR"
>    },
>    "destinationAmountDetails": {
>        "country": "NL",
>        "transactionAmount": 800,
>        "transactionCurrency": "EUR"
>    },
>    "timestamp": 1641654664,
>    "originPaymentDetails": {
>        "method": "IBAN",
>        "IBAN": "NL37RABO1954254121",
>        "BIC": "RABONL2U",
>        "bankName": "Rabobank"
>    }
>    "destinationPaymentDetails": {
>        "method": "IBAN",
>        "IBAN": "DE55500105178535472592",
>        "BIC": "INGDDEFFXXX",
>        "bankName": "ING"
>    }
>    }'