Account to Account (A2A) payments

Let’s take an example of a generic A2A payment 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

Merchants

A Merchant is represented as Business entity in the Flagright API. Everytime a new merchant 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

A2A Payments providers typically do not perform KYC on end users of the application - consumer users and do not have any information on the identity of the end users. If that’s the case for your system, you don’t have to create consumer users.

In case you capture the details of the end users (consumers - individuals on either side of the transaction), you would make an API to the POST /consumer/users endpoint to create a new consumer, 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.

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 A2A payments, there are typically two out of the three types of transactions:

User to Merchant (U2M)

A user-to-merchant is when a user transfers money from external source (typically, Bank account) to the bank account of the merchant (Business).

For U2M, the origin payment method and the destination payment method is the bank account type. In this case, the originUserId typically would be empty, since the user originating the payment isn’t the customer of the A2A payment provider and the A2A 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 Merchant 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": "TRANSFER",
> "destinationUserId": "9350a2611e0771cba03310f74bf6",
> "originAmountDetails": {
> "country": "NL",
> "transactionAmount": 800,
> "transactionCurrency": "EUR"
> },
> "destinationAmountDetails": {
> "country": "DE",
> "transactionAmount": 800,
> "transactionCurrency": "EUR"
> },
> "timestamp": 1641654664,
> "originPaymentDetails": {
> "method": "IBAN",
> "IBAN": "NL37RABO1954254121",
> "BIC": "RABONL2U",
> "bankName": "Rabobank"
>
> },
> "destinationPaymentDetails": {
> "method": "IBAN",
> "IBAN": "DE55500105178535472592",
> "BIC": "INGDDEFFXXX",
> "bankName": "ING"
> }
> }'

Merchant to User - Refund

A merchant-to-user is most often used for the cases of refunds. For refunds, the merchant (Business) is the originator of the A2A payment.

For Refunds, the origin payment method and the destination payment method is the bank account type. In this case, the destinationUserId typically would be empty, since the user receiving the payment isn’t the customer of the A2A payment provider and the A2A 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 destinationUserId

The originUserId would be the userId of the Merchant sending 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",
> "originUserId": "9350a2611e0771cba03310f74bf6",
> "originAmountDetails": {
> "country": "DE",
> "transactionAmount": 800,
> "transactionCurrency": "EUR"
> },
> "destinationAmountDetails": {
> "country": "NL",
> "transactionAmount": 800,
> "transactionCurrency": "EUR"
> },
> "timestamp": 1641654664,
> "originPaymentDetails": {
> "method": "IBAN",
> "IBAN": "DE55500105178535472592",
> "BIC": "INGDDEFFXXX",
> "bankName": "ING"
>
>
> },
> "destinationPaymentDetails": {
> "method": "IBAN",
> "IBAN": "NL37RABO1954254121",
> "BIC": "RABONL2U",
> "bankName": "Rabobank"
> }
> }'

Merchant to Merchant (M2M)

In cases where you enable M2M transactions, both the originator and destination would be of Business type, with originUserId and destinationUserId being the userId of the merchants.

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

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