Trustly APIs offer a secure and efficient way to process online payments. Use the information provided here to learn how to integrate Trustly APIs into your Money Transfer applications that support international transfers.

You initiate and process payments using the Trustly APIs, including adding the necessary data fields to ensure compliance with International Automated Clearing House Transaction (IAT) regulations. International Automated Clearing House Transaction (IAT) regulations are designed to enhance the security and transparency of cross-border payments. These regulations require you to include additional data fields with each transaction. This helps identify and mitigate the risk of money laundering, terrorist financing, and other financial crimes. Including the required IAT data for international money transfer payments ensures compliance with these regulations and helps maintain the integrity of the global financial system.

The following methodologies are available for international money transfers:

• Instant payment: Payments are initiated directly from the Trustly user interface (UI).
• Deferred payments : Your application stores a Trustly token, allowing a user to initiate payments without re-entering the Trustly UI.

Prerequisites

• You've completed a Trustly Pay integration using either a deferred or instant model.
• Familiarity with the Trustly APIs and basic Trustly UI integration concepts is recommended.
• 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 another merchantId for domestic transfers. If you do not have distinct MIDs, reach out to your Trustly representative and request an additional merchantId

International money transfer fields

If your application is configured for international money transfers, payment transactions must include all the required fields listed in the following sections. Including the optional fields can result in better approval results.

Originating customer details

Customer address object

Beneficiary

Provide the "beneficiary" or the ultimate recipient of the transfer. The model for the beneficiary object inherits from the customer object.

Beneficiary address object

Beneficiary financial account

Provide the financial account belonging to the beneficiary of the transfer. The model for the beneficiaryAccount contains a required paymentProvider object.

For any applicable Financial Account, include one (and only one) of the following three properties. Including more than one of these fields in a single request results in an error. You may omit these fields if none are available:

• iban: International Bank Account Number (IBAN)
• paymentProvider.routingNumber: Financial Institution Routing Number
• paymentProvider.swift: Financial Institution SWIFT code

Payment provider

The Payment Provider refers to the Financial Account associated with a customer or beneficiary.

Create an authorization

The primary difference in creating an authorization transaction for international money transfers is including 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.

Customer data

In the context of the Money Transfer transaction, the customer object represents the originator of the transfer and includes the customer's name and address. The beneficiary object in the payload initiating the payment represents the receiver of the transfer. For more information about these and other parameters, see the Establish a new transaction for authorization API.

If your application does not allow users to persist their account for additional transfers, see Instant payments.

The following is an example of the 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"
    }
  }
}

Initiate a payment

When making an international money transfer transaction you must include a beneficiary object containing the recipient's name and address as well as a beneficiaryAccount object containing the receiving bank's information. For more information about these and other parameters, see the Capture transaction API.

The following is an example of a 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. Use these 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.

Instant payments

If your application uses Instant payments by setting paymentType: Instant, the payment is processed after the user successfully completes the authorization. The Establish object that initiates the authorization must include the transfer receiver details in the beneficiary and beneficiaryAccount properties of the Establish object.

The following is an example of the 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"
    }
  }
}