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 another merchantId for domestic transfers. If you do not have distinct MIDs, reach out to your Trustly representative and request an additional merchantId.

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

Customer Address Object

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.

Beneficiary Address Object

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 Number
• paymentProvider.swift: Financial Institution SWIFT code

Payment Provider

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

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.

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.