Once you have a valid Bank Authorization, use the Trustly Transaction APIs to initiate Payments and Withdrawals.

Use the Capture Preauth API to validate Payments

The capture preauth API enables the merchant to pre-check payment approval. The ‘PreAuth’ is valid for a pre-authorized window interval in hours (default of 6 hours and up to 72 hours). Captures after the pre-authorized window interval are treated as normal Captures (will need to pass the full balance and risk analysis to be guaranteed).

Example Capture Preauth request

https://sandbox.trustly.one/api/v1/transactions/1001001894/capture/preauth/

passing the form parameters

{
  amount: 10.00,
  period: 4,
  merchantReference:  "BE3C26BC3F713AF8"
}

The response might be:

{
    "transaction": {
    "transactionId": "1001001894",
    "transactionType": 2,
    "currency": "USD",
    "amount": "10.0",
    "status": 2,
    "statusMessage": "Authorized",
    "ip": "192.168.100.147",
    "createdAt": 1449176555750,
    "updatedAt": 1449176576137,
    "merchantReference": "BE3C26BC3F713AF8",
    "recordVersion": 3,
    "payment": {
    "paymentId": "1001001891",
    "paymentType": 1,
    "merchant": {
    "merchantId": "110005502"
    },
    "merchantReference": "BE3C26BC3F713AF8",
    "fingerprint": "eaGRmtHdk23hA7U2zB5TmDAJjDE=",
    "verification": {
        "status": 3,
        "mode": 3,
        "verifyCustomer": false
        },
        "account": {
        "name": "Demo Checking Account",
        "type": -1,
        "profile": -1,
        "accountNumber": "6576",
        "token": "KSDF23KL6576",
        "verified": true,
        "verification": {
        "type": 2
        },
        "source": 1
        },
        "description": "Merchant.com purchase #BE3C26BC3F713AF8",
        "returnUrl": "https://merchant.com/instant/receipt",
        "cancelUrl": "https://merchant.com/instant/cancel",
        "currency": "USD",
        "amount": "2.10",
        "paymentProvider": {
        "paymentProviderId": "200005501",
        "type": 1,
        "name": "Demo Bank"
        },
        "auth": {
        "token": "1001000020",
        "status": 2,
        "message": "Authorized"
        },
        "createdAt": 1449176555744,
        "updatedAt": 1449176576159,
        "recordVersion": 5,
        "paymentFlow": 59
        }
    }
}

Use the Capture API to initiate Payments

The Capture API allows the merchant to request the transfer of a specific amount from the Users Bank Account given a Bank Account Authorization. You call the Capture API by executing a POST request to the Capture endpoint (/transactions/{transactionId}/capture), where {transactionId} is the Bank Account Authorization transaction id. This API returns one of the following 3 responses:

• PENDING: The transaction was accepted and is in progress. You will be notified via Event Notification of the final disposition of the transaction. For Guaranteed Payments, that will happen within 3-10 seconds. For non-Guaranteed Payments, that will happen within 3 banking days.
• DECLINED: The transaction was declined and the User should be message appropriately (see Error Handling).
• ERROR: There was an error processing the request. Correct the error and try the request again (see Error Handling).

If the transaction was accepted for processing, the Capture API returns a PENDING transaction. You should create a PENDING transaction in your system and message the User appropriately.

📘

Info

A PENDING transaction will trigger an Authorized event notification. Additional event notifications will be triggered as the transaction is processed. For a complete list of transaction statuses and their transitions, refer to the State Transition Diagram below.

In order to execute the Capture API request, ensure you pass in the following fields:

• amount: Amount to be captured.
• merchantReference: Your specific identifier for this transaction. For example, this could be your Order Number or the same merchant reference value used in the Bank Authorization transaction. This will appear in Event Notifications and Reports.

📘

Info

To avoid duplicate transactions, Trustly supports idempotency. If you are unable to support this requirement, please contact support. To learn more, see Idempotency.

Example Capture request

amount=10.00&merchantReference=9ce392f7-f99b-41e9-9028-3f33c8b0a46e

📘

Tip

If you wish to have the User wait while the transaction with Trustly processes, you should create the pending transaction in your system, display an appropriate processing message to the user, and periodically check the status of the Users transaction in your system. Once the Event Notification is received and you update the status of the Users transaction, you can display the appropriate message. Set a timeout of 10 seconds in your application. If you don't receive an Event Notification in your system in 10 seconds, execute a Cancel API and attempt the request again.

Example Capture response (abbreviated)

{
  "transaction": {
    "transactionId": "1002636615",
    "transactionType": 3,
    "originalTransactionId": "1002636593",
    "payment": {
      "paymentId": "1002636591",
      "paymentType": 2,
      "merchantReference": "123123",
      "account": {
        "name": "Demo Checking Account",
        "type": 1,
        "profile": 1,
        "accountNumber": "6576",
      },
      "description": "Order",
      "paymentProvider": {
        "paymentProviderId": "200005501",
        "type": 1,
        "name": "Demo Bank"
      },
      "auth": {
        "token": "15LDRA3ENERD",
        "status": 2,
        "message": "Authorized"
      },
      "authorization": "15LDRA3ENERD",
      "authorizationStatus": 2,
      "authorizationStatusMessage": "Authorized",
    },
    "currency": "USD|CAD",
    "amount": "10.00",
    "pending": "10.00",
    "paymentProviderTransaction": {
      "paymentProviderTransactionId": "ptx-ynFSa0oAiaIruwksqTtasJOX-sbx",
      "status": 10,
      "statusMessage": "Established",
      "paymentProcessor": {
        "paymentProcessorId": "100000001"
      }
    },
    "status": 1,
    "statusMessage": "Pending",
    "merchantReference": "4160903e-4ef6-49c3-a186-69b51787e638",
    "statusCode": "SW010",
  }
}

Please refer to the Capture Transaction definition in the API Reference for more information.

Use the Deposit API to initiate Withdrawals

The Deposit API allows the merchant to request the transfer of a specific amount to the Users Bank Account given a Bank Account Authorization. You call the Deposit API by executing a POST request to the Deposit endpoint (/transactions/{transactionId}/deposit), where {transactionId} is the Bank Account Authorization transaction id. This API returns one of the following 3 responses:

• AUTHORIZED: The transaction was accepted and is in progress. You will be notified via Event Notifications of the final disposition of the transaction, usually within 3 banking days.
• DECLINED: The transaction was declined and the User should be message appropriately (see Error Handling).
• ERROR: There was an error processing the request. Correct the error and try the request again (see Error Handling).

If the transaction was accepted for processing, the Deposit API returns an AUTHORIZED transaction. You should create a PENDING transaction in your system and message the User appropriately.

📘

Info

A PENDING transaction will trigger an Authorized event notification. Additional event notifications will be triggered as the transaction is processed. For a complete list of transaction statuses and their transitions, refer to the State Transition Diagram below.

In order to execute the Deposit API request, ensure you pass in the following fields:

• amount: Amount to be captured.
• merchantReference: Your specific identifier for this transaction. For example, this could be your Order Number or the same merchant reference value used in the Bank Authorization transaction. This will appear in Event Notifications and Reports.

Example Deposit request

amount=25.00&merchantReference=5b83cfe7-b43c-4a6a-aec3-e483876a908a

Example Deposit response (abbreviated)

{
    "transaction": {
        "transactionId": "1002636638",
        "transactionType": 6,
        "originalTransactionId": "1002636593",
        "payment": {
            "paymentId": "1002636591",
            "paymentType": 2,
            "merchantReference": "123123",
            "account": {
                "name": "Demo Checking Account",
                "type": 1,
                "profile": 1,
                "accountNumber": "6576",
            },
            "description": "Order",
            "paymentProvider": {
                "paymentProviderId": "200005501",
                "type": 1,
                "name": "Demo Bank"
            },
            "auth": {
                "token": "15LDRA3ENERD",
                "status": 2,
                "message": "Authorized"
            },
            "authorization": "15LDRA3ENERD",
            "authorizationStatus": 2,
            "authorizationStatusMessage": "Authorized",
        },
        "currency": "USD|CAD",
       "amount": "25.00",
        "pending": "25.00",
        "paymentProviderTransaction": {
            "paymentProviderTransactionId": "ptx-6ygGA5gI7smyLVx52DY9D5oH-sbx",
            "status": 100,
            "statusMessage": "Pending",
            "paymentProcessor": {
                "paymentProcessorId": "100000001"
            }
        },
        "status": 2,
        "statusMessage": "Authorized",
        "merchantReference": "2534256c-634f-4ac6-a0dd-75d502cb1c3c",
        "statusCode": "AC100",
    }
}

Please refer to the Deposit API definition in the API Reference for more information.

Other Transaction APIs

Trustly offers a number of other APIs that can be used to process Payment Transactions as needed.

• Refund Transaction: Use to refund a previously completed Capture transaction.
• Reclaim Transaction: Use to refund a previously completed Deposit transaction.
• Cancel Transaction: Use to cancel a previously authorized Bank Authorization or unsettled Capture transaction.

Common Failure Scenarios

Common failure scenarios are outlined in the table below.

Next Steps

Now that you have enabled payment transactions in your application, the final steps to completing your Trustly Pay integration involve handling event notifications. To indicate the status of the payment, Trustly will send your pre-configured notificationUrl event notifications (or webhooks). Learn how to handle these events in the next section.