International Money Transfer
Trustly's APIs offer a secure and efficient way to process online payments. This guide will walk you through the process of integrating Trustly's APIs into your platform while meeting requirements for Money Transfer applications who support International transfers.
You will learn how to initiate and process payments using Trustly's APIs, including how to add necessary data fields to ensure compliance with International ACH Transaction (IAT) regulations. By the end of this tutorial, you will have a clear understanding of how to leverage Trustly's APIs to enhance your payment processing capabilities.
Requirements for International Money Transfer Applications
If your application is configured for
International Money Transfer
attempting to provide the data listed in this guide in the relevant functions and objects is required. Failing to include these data over prolonged periods may result in disruption of service.
Background
International ACH Transactions (IAT) are governed by regulations designed to enhance the security and transparency of cross-border payments. These regulations require additional data fields to be included with each transaction to help identify and mitigate the risk of money laundering, terrorist financing, and other financial crimes. For Money Transfer payments processed through Trustly's platform, including the required IAT data ensures compliance with these regulations and helps maintain the integrity of the global financial system.
This guide will cover both an Instant Payment model where payments are initiated directly from the Trustly UI as well as a Deferred Payments model where a Trustly token is stored in your application so a user can initiate payments without re-entering the Trustly UI.
Prerequisites
This guide assumes that you have already completed an integration for Trustly Pay using either a deferred or instant model. Familiarity with Trustly's API and basic Trustly UI integration concepts is recommended. If you have not yet integrated Trustly's payment methods, we recommend starting there.
Domestic Money Transfer Applications
If your application is configured for both domestic and international money transfers you must use distinct merchant identifiers (MIDs) for each case; one
merchantId
for international transfers and anothermerchantId
for domestic transfers. If you do not have distinct MIDs, reach out to your Trustly representative and request an additionalmerchantId
.
Summary of Money Transfer Fields
If your application is configured for Money Transfer, payment transactions should include all Required fields listed in the sections below. Additionally, including optional fields listed here may result in better approval results, therefore including all listed fields when possible is recommended.
Note on Required Fields
Use of the term "required" in the tables below is in reference to International Money Transfer applications. If your application is not configured for International Money Transfers these fields are not required.
If your application is configured for International Money Transfer and any of these fields are not available, they may be omitted. However, including as many of these fields as possible will decrease the likelihood of the transaction being flagged by the various screening processes involved with international money transfers.
Originating Customer Details
Property | Type | Required | Description |
---|---|---|---|
name | String | True | Customer full legal name |
address | Object | True | See Address object below |
dateOfBirth | String | False | Customer date of birth |
taxId | String | False | Customer tax ID (e.g. SSN for US or SIN for CA) |
Customer Address Object
Property | Type | Required | Description |
---|---|---|---|
address1 | String | True | Address line 1 (e.g., street or PO Box) |
address2 | String | False | Address line 2 (e.g., apartment, suite or unit number) |
city | String | True | City, district, town or village |
state | String | True | State, province or region |
zip | String | True | Postal code |
country | String | True | ISO 3166 Country code |
Beneficiary
The "beneficiary" or the ultimate recipient of the transfer must be provided. The model for the beneficiary
object is inherited from the customer
object.
Property | Type | Required | Description |
---|---|---|---|
name | String | True | Customer full name |
address | Object | True | See Beneficiary Address object below |
dateOfBirth | String | False | Customer date of birth |
taxId | String | False | Customer tax ID (e.g. SSN for US or SIN for CA) |
Beneficiary Address Object
Property | Type | Required | Description |
---|---|---|---|
address1 | String | False | Address line 1 (e.g., street or PO Box) |
address2 | String | False | Address line 2 (e.g., apartment, suite or unit number) |
city | String | False | City, district, town or village |
state | String | False | State, province or region |
zip | String | False | Postal code |
country | String | True | ISO 3166 Country code |
Beneficiary Financial Account
The Financial Account belonging to the beneficiary of the transfer must be provided. The model for the beneficiaryAccount
contains a required paymentProvider
object.
For any applicable Financial Account, one (and only one) of the following three properties should be included. Including more than one of these fields in a single request will result in an error and if none are available, these fields may be omitted:
iban
: International Bank Account Number (IBAN)paymentProvider.routingNumber
: Financial Institution Routing NumberpaymentProvider.swift
: Financial Institution SWIFT code
Property | Type | Required | Description |
---|---|---|---|
paymentProvider | Object | False | See Payment Provider object below |
iban | String | False | International Bank Account Number (IBAN) |
accountNumber | String | False | Financial Institution Account Number |
Payment Provider
The Payment Provider refers to the Financial Account associated with a customer or beneficiary.
Property | Type | Required | Description |
---|---|---|---|
name | String | False | Financial Institution name |
country | String | False | Financial Institution country code (ISO 3166) |
swift | String | False | International SWIFT code |
routingNumber | String | False | Financial Institution Routing Number |
Creating an Authorization
The primary difference in creating an Authorization transaction for Money Transfer is the inclusion of additional compliance data. IAT regulations require specific information to be included with each transaction, such as the originator's name, address, and country, to ensure transparency and security in cross-border transactions. These additional data fields are necessary to meet compliance standards and help prevent money laundering, terrorist financing, and other financial crimes. In this section, we will guide you through the process of including this compliance data in your Authorization transaction for Money Transfer using Trustly's API.
Customer Data
In the context of the Money Transfer transaction, the originator of the transfer will be represented by the customer
object, which includes the customer's name and address. The receiver of the transfer will be represented by the beneficiary
object included on the payload initiating the payment. If your application does not allow users to persist their account for additional transfers, skip ahead to the Instant Payments section.
See more details on the Establish a new Transaction API reference.
Example Establish Data Object for Deferred Transfers
{
"merchantId": "YOUR_MERCHANT_ID",
"accessId": "YOUR_ACCESS_ID",
"merchantReference": "",
"paymentType": "Deferred",
"customer": {
"name": "Joe User",
"taxId": "017-27-3353",
"dateOfBirth": "09/11/1986",
"address": {
"address1": "2000 Broadway St",
"city": "Redwood City",
"state": "CA",
"zip": "94063",
"country": "US"
}
}
}
Initiating Payment
When making a payment transaction, the transfer receiver details are also required. Include a beneficiary
object containing the recipient's name
and address
as well as a beneficiaryAccount
object containing the receiving bank's information.
See more details on the Capture transaction API reference.
Example Capture Request
curl --request POST \
--url https://sandbox.trustly.one/api/v1/transactions/transactionId/capture \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'accept: application/json' \
--data merchantReference=607E61428FCAED32 \
--data amount=200.00 \
--data 'beneficiaryAccount.accountNumber=762011623852957' \
--data 'beneficiaryAccount.paymentProvider.name=UBS Switzerland' \
--data 'beneficiaryAccount.paymentProvider.country=CH' \
--data 'beneficiaryAccount.paymentProvider.swift=UBSWCHZH80A' \
--data 'beneficiary.address.address1=Untere Bahnhofstrasse 90' \
--data 'beneficiary.address.city=Castiel' \
--data 'beneficiary.address.state=Graubünden' \
--data 'beneficiary.address.zip=7027' \
--data 'beneficiary.address.country=CH'
{
"amount": "250.00",
"beneficiary": {
"address": {
"address1": "Untere Bahnhofstrasse 90",
"city": "Castiel",
"state": "Graubünden",
"zip": 7027,
"country": "CH"
},
"name": "Johan Olen",
"taxId": "756.9217.0769.85",
"dateOfBirth": "08/08/1998"
},
"beneficiaryAccount": {
"paymentProvider": {
"name": "Swiss National Bank",
"swift": "SNBZCHZZXXX",
"country": "CH"
},
"accountNumber": 762011623852957
}
}
Remittance Data
The Capture API also supports additional data points which should be used when available to ensure the highest levels of payment approvals and quicker processing times. These data points are structured under a remittance
object which is a property of the metadata
object.
Property | Type | Required | Description |
---|---|---|---|
withdrawalMethod | String | False | Method of withdrawal for the ultimate beneficiary. Can be BankDeposit , Cash , DebitCard , DigitalWallet or HomeDelivery . |
countryCorridor | String | False | The location to which the money is being sent, represented by a two-letter ISO 3166 alpha-2 country code. |
accountLastFour | Number | False | Last four digits of the associated bank account if withdrawalMethod is BankDeposit or DebitCard . |
Instant Payments
If your application uses Instant payments by setting paymentType: Instant
, the payment will be processed after the user successfully completes the authorization. Therefore the Establish object that initiates the authorization must include the transfer receiver details via the beneficiary
and beneficiaryAccount
properties in the Establish object.
Example Establish Data Object for Instant Transfers
{
"merchantId": "110005514",
"accessId": "A48B73F694C4C8EE6306",
"merchantReference": "ABCDE12345",
"paymentType": "Instant",
"amount": "250.00",
"description": "Readable transfer description",
"returnUrl": "http://yourdomain.com/return",
"cancelUrl": "http://yourdomain.com/cancel",
"notificationUrl": "http://yourdomain.com/notification?",
"requestSignature": "a/n62XqfgQA31xmFnCxNEOjd7g=",
"currency": "USD",
"customer": {
"address": {
"address1": "2000 Broadway St",
"city": "Redwood City",
"state": "CA",
"zip": "94063",
"country": "US"
},
"name": "John Smith",
"email": "[email protected]",
"phone": "+19019958789",
"dateOfBirth": "09/09/1990"
},
"beneficiary": {
"address": {
"address1": "Untere Bahnhofstrasse 90",
"city": "Castiel",
"state": "Graubünden",
"zip": 7027,
"country": "CH"
},
"name": "Johan Olen",
"taxId": "756.9217.0769.85",
"dateOfBirth": "08/08/1998"
},
"beneficiaryAccount": {
"accountNumber": 762011623852957,
"paymentProvider": {
"name": "Swiss National Bank",
"swift": "SNBZCHZZXXX",
"country": "CH"
}
}
}
Summary
To summarize, Trustly's APIs enable secure and efficient online payment processing, including international transfers. This guide helps integrate Trustly's APIs for Money Transfer applications, ensuring compliance with International ACH Transaction (IAT) regulations.
If you are unsure if your application should be configured for International Money Transfer, contact your Trustly representative.
Updated 2 months ago