1 of 5

Create outgoing payments

In this section, you will find instructions on how to create the following types of outgoing payments:

Create SEPA payment

Use case

In this scenario, we will create an outgoing SEPA payment - ACC2SEPA payment type.

Use case data

API parameters with values

Our party details gives the information about the sender of the payment. In this example, the payment is initialised from the Tuum account ID-4184.

Counterparty details.

Payment amount and currency.

Payment details.

The payment also includes payment steering data, such as valueDate and ourFee. Note: the valueDate and ourFee parameters are optional.

Sample API call

To initialise the payment, use the following endpoint:

https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise

Learn more about the initialise payment endpoint endpoint in the Tuum developer portal.

Sample request

The sample request body is as follows:

{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountId": "ID-4184"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "EE871275295834652820",
                "type": "IBAN"
            }
        }
    ],
    "money": {
        "amount": 25,
        "currencyCode": "EUR"
    },
    "details": "Test payment with our party accountId",
    "valueDate" : "2024-12-04",
    "ourFee": {
         "amount": 1.22,
         "currencyCode": "EUR"
  }
}

curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDRUMTQ6MjY6MTkiLCJleHAiOjE3MzMzMjIzNzksInJvbGVzIjpbIkFETUlOIl19.X1C4fpzVoXZnbicLPFW7izPPRLKGs-wGw6xoETGAypE' \
--header 'Content-Type: application/json' \
--data '{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountId": "ID-4184"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "EE871275295834652820",
                "type": "IBAN"
            }
        }
    ],
    "money": {
        "amount": 25,
        "currencyCode": "EUR"
    },
    "details": "Test payment with our party accountId",
    "valueDate" : "2024-12-04",
    "ourFee": {
         "amount": 1.22,
         "currencyCode": "EUR"
  }
}'

Sample response

Below you will find the response to the sample request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "paymentId": "PAYM-32706",
        "accountId": "ID-4184",
        "directionCode": "OUT",
        "statusCode": "INSERTED",
        "errorCode": null,
        "money": {
            "amount": 25.00,
            "currencyCode": "EUR"
        },
        "details": "Test payment with our party accountId",
        "referenceNumber": null,
        "source": null,
        "contractSource": null,
        "endToEndId": null,
        "valueDate": "2024-12-04",
        "postingDate": "2024-12-04",
        "insertedDateTime": "2024-12-04T13:28:52.498788Z",
        "paymentServiceProviderCode": "SEPA",
        "paymentTypeCode": "ACC2SEPA",
        "preferredPaymentScheme": null,
        "selectedPaymentScheme": "SEPA_INSTANT",
        "chargeBearer": null,
        "settlementStatusCode": null,
        "settlementErrorCode": null,
        "settlementDate": null,
        "settlementPaymentScheme": null,
        "returnStatusCode": null,
        "returnReason": null,
        "returnComment": null,
        "returnSettlementDate": null,
        "cancellationRequestStatusCode": null,
        "cancelRefuseReason": null,
        "cancelReason": null,
        "amlDeclineReason": null,
        "amlMonitoringEnabled": null,
        "lastStatusRequestDate": null,
        "residencyCountryCode": "GB",
        "counterpartyOriginalIban": null,
        "fxPaymentFlag": false,
        "fxPayment": null,
        "paymentParties": [
            {
                "paymentPartyId": "PAYM-67504",
                "typeCode": "COUNTERPARTY",
                "name": "Robert Receiver",
                "personTypeCode": null,
                "givenName": null,
                "surname": null,
                "accountNumber": {
                    "value": "EE871275295834652820",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "EE",
                "financialInstitutionId": {
                    "value": "PARXEE22XXX",
                    "type": "BIC"
                },
                "address": null,
                "roleCode": "BENEFICIARY",
                "partyIdentification": null
            },
            {
                "paymentPartyId": "PAYM-67505",
                "typeCode": "OUR_PARTY",
                "name": "Tuum Thomas",
                "personTypeCode": "P",
                "givenName": "Tuum",
                "surname": "Thomas",
                "accountNumber": {
                    "value": "XX20XXXX99999000000000000021075",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "XX",
                "financialInstitutionId": {
                    "value": "ICECLOUDXXX",
                    "type": "BIC"
                },
                "address": {
                    "street1": "24 Botley Road",
                    "street2": null,
                    "cityCounty": "Middleton Hall",
                    "stateRegion": null,
                    "zip": "NE71 3LL",
                    "countryCode": "GB",
                    "addressLine": "24 Botley Road, Middleton Hall, GB, NE71 3LL",
                    "addressTypeCode": null
                },
                "roleCode": "PAYER",
                "partyIdentification": {
                    "identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
                    "identificationValue": "DD654321C"
                }
            }
        ],
        "fees": [
            {
                "feeTypeCode": "ACC2SEPA_FEE",
                "feeMoney": {
                    "amount": 1.22,
                    "currencyCode": "EUR"
                },
                "deferredFee": false
            }
        ],
        "paymentSchemeElements": [],
        "fileImportLineNumber": null,
        "purposeCode": null,
        "labels": [
            "COUNTERPARTY_EE",
            "SEPA_INSTANT"
        ]
    }
}

Result

The draft payment has been created with a paymentId: PAYM-32706 and the statusCode: INSERTED.

Possible next steps

After creating a draft payment, you have the following options:

Change the draft payment - modify the draft payment.
Cancel the draft payment - discard the draft payment if it is no longer required.
Confirm the draft payment - complete payment to initiate further payment processing.

Create SWIFT payment

Use case

In this scenario, we will initialise an outgoing SWIFT (cross border) payment to a counterparty account with an IBAN and some sample data - ACC2SWIFT payment type.

Use case data

API parameters with values

Our party details gives the information about the sender of the payment. In this example, the payment is initialised from the Tuum account ID-1887.

Counterparty details.

Payment amount.

Payment details.

The payment also includes additional transferable data, such as chargeBearer and endToEndId. Note: the chargeBearer and endToEndId parameters are optional.

Sample API call

To initialise the payment, use the following endpoint:

https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise

Learn more about the initialise payment endpoint in the Tuum developer portal.

Sample request

The sample request body is as follows:

{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountId": "ID-21508"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Ben Eficiary",
            "accountNumber": {
                "value": "EE871275295834652820",
                "type": "IBAN"
            },
            "financialInstitutionId": "PARXEE22XXX",
            "address": {
                "street1": "First street 123",
                "street2": "Second street 321",
                "cityCounty": "Some city",
                "zip": "06777",
                "countryCode": "EE"
            }
        }
    ],
    "money": {
        "amount": 1,
        "currencyCode": "DKK"
    },
    "details": "Test payment",
    "endToEndId": "20240103-E000003",
    "chargeBearer": "DEBT"
}

curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDZUMTM6Mjc6MzUiLCJleHAiOjE3MzM0OTE2NTUsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.r4Efnh8m_waGXaTRBQDLhLDb2M6no_SRJpZCGPoO6K8' \
--header 'Content-Type: application/json' \
--data '{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountId": "ID-21508"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Ben Eficiary",
            "accountNumber": {
                "value": "EE871275295834652820",
                "type": "IBAN"
            },
            "financialInstitutionId": "PARXEE22XXX",
            "address": {
                "street1": "First street 123",
                "street2": "Second street 321",
                "cityCounty": "Some city",
                "zip": "06777",
                "countryCode": "EE"
            }
        }
    ],
    "money": {
        "amount": 1,
        "currencyCode": "DKK"
    },
    "details": "Test payment",
    "endToEndId": "20240103-E000003",
    "chargeBearer": "DEBT"
}'

Sample response

Below you will find the response to the sample request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "paymentId": "PAYM-21846",
        "accountId": "ID-21508",
        "directionCode": "OUT",
        "statusCode": "INSERTED",
        "errorCode": null,
        "money": {
            "amount": 1.00,
            "currencyCode": "DKK"
        },
        "details": "Test payment",
        "referenceNumber": null,
        "source": null,
        "contractSource": null,
        "endToEndId": "20240103-E000003",
        "valueDate": "2029-12-02",
        "postingDate": "2029-12-02",
        "insertedDateTime": "2024-12-06T12:41:45.629822Z",
        "paymentServiceProviderCode": "SWIFT",
        "paymentTypeCode": "ACC2SWIFT",
        "preferredPaymentScheme": null,
        "selectedPaymentScheme": null,
        "chargeBearer": "DEBT",
        "settlementStatusCode": null,
        "settlementErrorCode": null,
        "settlementDate": null,
        "settlementPaymentScheme": null,
        "returnStatusCode": null,
        "returnReason": null,
        "returnComment": null,
        "returnSettlementDate": null,
        "cancellationRequestStatusCode": null,
        "cancelRefuseReason": null,
        "cancelReason": null,
        "amlDeclineReason": null,
        "amlMonitoringEnabled": null,
        "lastStatusRequestDate": null,
        "residencyCountryCode": "EE",
        "counterpartyOriginalIban": null,
        "fxPaymentFlag": false,
        "fxPayment": null,
        "paymentParties": [
            {
                "paymentPartyId": "PAYM-57584",
                "typeCode": "COUNTERPARTY",
                "name": "Ben Eficiary",
                "personTypeCode": null,
                "givenName": null,
                "surname": null,
                "accountNumber": {
                    "value": "EE871275295834652820",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "EE",
                "financialInstitutionId": {
                    "value": "PARXEE22XXX",
                    "type": "BIC"
                },
                "address": {
                    "street1": "First street 123",
                    "street2": "Second street 321",
                    "cityCounty": "Some city",
                    "stateRegion": null,
                    "zip": "06777",
                    "countryCode": "EE",
                    "addressLine": "First street 123, Second street 321, Some city, EE, 06777",
                    "addressTypeCode": null
                },
                "roleCode": "BENEFICIARY",
                "partyIdentification": null
            },
            {
                "paymentPartyId": "PAYM-57585",
                "typeCode": "OUR_PARTY",
                "name": "Test Payer",
                "personTypeCode": "P",
                "givenName": null,
                "surname": null,
                "accountNumber": {
                    "value": "XX46XXXX99999000000000000111011",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "XX",
                "financialInstitutionId": {
                    "value": "ICECLOUDXXX",
                    "type": "BIC"
                },
                "address": {
                    "street1": "Tartu mnt 32-25",
                    "street2": null,
                    "cityCounty": "Harjumaa",
                    "stateRegion": "Tallinn",
                    "zip": "10115",
                    "countryCode": "EE",
                    "addressLine": "Tartu mnt 32-25, Harjumaa, EE, 10115",
                    "addressTypeCode": null
                },
                "roleCode": "PAYER",
                "partyIdentification": {
                    "identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
                    "identificationValue": "314-494-5904"
                }
            }
        ],
        "fees": [],
        "paymentSchemeElements": [],
        "fileImportLineNumber": null,
        "purposeCode": null,
        "labels": [
            "COUNTERPARTY_EE"
        ]
    }
}

Result

The draft payment has been created with a paymentId: PAYM-21846 and the statusCode: INSERTED.

Possible next steps

After creating a draft payment, you have the following options:

Change the draft payment - modify the draft payment.
Cancel the draft payment - discard the draft payment if it is no longer required.
Confirm the draft payment - complete payment to initiate further payment processing.

Create domestic UK payment

Here, you can find one of the examples of how to create a draft payment using the .

Use case

In this scenario, we will create a domestic UK payment from Tuum BC (Banking Circle) UK account to another UK account. In this case, the payment will be created with the ACC2LOCAL payment type.

Use case data

API parameters with values

Our party details give the information about the sender of the payment. In this example, the payment is initialised from the Tuum bank account with 21824474 BBAN.

The payer's account country is the UK. Note: the payer's bank account financial institution id is the bank's sort code.

Counterparty details.

The payment receiver account country is the UK. Note: the payment receiver financial institution id is the bank's sort code.

Payment amount and currency.

Payment details.

The payment also includes non-transferrable data, such as contractSource. Note: the contractSource parameter is optional.

Sample API call

To initialise the payment, use the following endpoint: https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise

Learn more about the initialise payment endpoint endpoint in the Tuum developer portal.

Sample request

The sample request body is as follows:

{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountNumber": {
                "value": "21824474",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "608382"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "00001781",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "040300"
        }
    ],
    "money": {
        "amount": 15,
        "currencyCode": "GBP"
    },
    "details": "Test payment with both parties with BBAN for domestic UK payment",
    "contractSource": {
    "sourceName": "Test System",
    "sourceRef": "1234",
    "contractNumber": "test"
  }
}

curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDVUMTM6MTA6MDciLCJleHAiOjE3MzM0MDQyMDcsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.T2c1I6mazgGm2gT6p3lqaXxb2qj9OTPiluP5XnJr0zU' \
--header 'Content-Type: application/json' \
--data '{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountNumber": {
                "value": "21824474",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "608382"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "00001781",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "040300"
        }
    ],
    "money": {
        "amount": 15,
        "currencyCode": "GBP"
    },
    "details": "Test payment with both parties with BBAN for domestic UK payment",
    "contractSource": {
    "sourceName": "Test System",
    "sourceRef": "1234",
    "contractNumber": "test"
  }
}'

Sample response

Below you will find the response to the sample request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "paymentId": "PAYM-21826",
        "accountId": "ID-17598",
        "directionCode": "OUT",
        "statusCode": "INSERTED",
        "errorCode": null,
        "money": {
            "amount": 15.00,
            "currencyCode": "GBP"
        },
        "details": "Test payment with both parties with BBAN for domestic UK payment",
        "referenceNumber": null,
        "source": null,
        "contractSource": {
            "sourceName": "Test System",
            "sourceRef": "1234",
            "contractNumber": "test"
        },
        "endToEndId": null,
        "valueDate": "2029-11-27",
        "postingDate": "2029-11-27",
        "insertedDateTime": "2024-12-05T12:21:07.149343Z",
        "paymentServiceProviderCode": "BC",
        "paymentTypeCode": "ACC2LOCAL",
        "preferredPaymentScheme": null,
        "selectedPaymentScheme": null,
        "chargeBearer": null,
        "settlementStatusCode": null,
        "settlementErrorCode": null,
        "settlementDate": null,
        "settlementPaymentScheme": null,
        "returnStatusCode": null,
        "returnReason": null,
        "returnComment": null,
        "returnSettlementDate": null,
        "cancellationRequestStatusCode": null,
        "cancelRefuseReason": null,
        "cancelReason": null,
        "amlDeclineReason": null,
        "amlMonitoringEnabled": null,
        "lastStatusRequestDate": null,
        "residencyCountryCode": "FI",
        "counterpartyOriginalIban": null,
        "fxPaymentFlag": false,
        "fxPayment": null,
        "paymentParties": [
            {
                "paymentPartyId": "PAYM-57538",
                "typeCode": "COUNTERPARTY",
                "name": "Robert Receiver",
                "personTypeCode": null,
                "givenName": null,
                "surname": null,
                "accountNumber": {
                    "value": "00001781",
                    "type": "BBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "GB",
                "financialInstitutionId": {
                    "value": "040300",
                    "type": "SORT_CODE"
                },
                "address": null,
                "roleCode": "BENEFICIARY",
                "partyIdentification": null
            },
            {
                "paymentPartyId": "PAYM-57539",
                "typeCode": "OUR_PARTY",
                "name": "Daria Core",
                "personTypeCode": "P",
                "givenName": "Daria",
                "surname": "Core",
                "accountNumber": {
                    "value": "DK9189000021824474",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "DK",
                "financialInstitutionId": {
                    "value": "SXPYDKKK",
                    "type": "BIC"
                },
                "address": {
                    "street1": "Maakri",
                    "street2": null,
                    "cityCounty": "Tallinn",
                    "stateRegion": null,
                    "zip": null,
                    "countryCode": "EE",
                    "addressLine": "Maakri, Tallinn, EE",
                    "addressTypeCode": null
                },
                "roleCode": "PAYER",
                "partyIdentification": {
                    "identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
                    "identificationValue": "EE1234567"
                }
            }
        ],
        "fees": [],
        "paymentSchemeElements": [],
        "fileImportLineNumber": null,
        "purposeCode": null,
        "labels": [
            "COUNTERPARTY_GB"
        ]
    }
}

Result

The draft payment has been created with a paymentId: PAYM-21826 and the statusCode: INSERTED.

Possible next steps

After creating a draft payment, you have the following options:

Change the draft payment - modify the draft payment.
Cancel the draft payment - discard the draft payment if it is no longer required.
Confirm the draft payment - complete payment to initiate further payment processing.

Create domestic US payment

Here, you can find one of the examples of how to create a draft payment using the .

Use case

In this scenario, we will create a domestic US payment - ACC2LOCAL payment type.

Use case data

API parameters with values

Our party details gives the information about the sender of the payment. In this example, the payment is initialised from the Tuum bank account with 190021824474 BBAN.

The payer's account country is the USA. Note: the payer's bank account financial institution id is the ABA Routing number.

Counterparty details.

The payer's account country is the USA. Note: the payer's bank account financial institution id is the ABA Routing number.

Payment amount and currency.

Payment details.

The payment also includes payment steering data, such as usageLimitCode. Note: the usageLimitCode is an optional parameter.

Sample API call

To initialise the payment, use the following endpoint: https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise

Learn more about the initialise payment endpoint endpoint in the Tuum developer portal.

Sample request

The sample request body is as follows:

{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountNumber": {
                "value": "190021824474",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "US",
            "financialInstitutionId": "021000018"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "231123456789",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "US",
            "financialInstitutionId": "021000322"
        }
    ],
    "money": {
        "amount": 17,
        "currencyCode": "USD"
    },
    "details": "Test payment with both parties with BBAN for domestic US payment",
    "usageLimitCode": "test"
}

curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDVUMTM6NDM6MTAiLCJleHAiOjE3MzM0MDYxOTAsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.03a1hgsWy3yZxxKXl-TpIatf4XAllaA0dquZH4U8a0E' \
--header 'Content-Type: application/json' \
--data '{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountNumber": {
                "value": "190021824474",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "US",
            "financialInstitutionId": "021000018"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "231123456789",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "US",
            "financialInstitutionId": "021000322"
        }
    ],
    "money": {
        "amount": 17,
        "currencyCode": "USD"
    },
    "details": "Test payment with both parties with BBAN for domestic US payment",
    "usageLimitCode": "test"
}'

Sample response

Below you will find the response to the sample request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "paymentId": "PAYM-21726",
        "accountId": "ID-17598",
        "directionCode": "OUT",
        "statusCode": "INSERTED",
        "errorCode": null,
        "money": {
            "amount": 17.00,
            "currencyCode": "USD"
        },
        "details": "Test payment with both parties with BBAN for domestic US payment",
        "referenceNumber": null,
        "source": null,
        "contractSource": null,
        "endToEndId": null,
        "valueDate": "2029-11-01",
        "postingDate": "2029-11-01",
        "insertedDateTime": "2024-11-28T16:09:32.4368Z",
        "paymentServiceProviderCode": "BC",
        "paymentTypeCode": "ACC2LOCAL",
        "preferredPaymentScheme": null,
        "selectedPaymentScheme": null,
        "chargeBearer": null,
        "settlementStatusCode": null,
        "settlementErrorCode": null,
        "settlementDate": null,
        "settlementPaymentScheme": null,
        "returnStatusCode": null,
        "returnReason": null,
        "returnComment": null,
        "returnSettlementDate": null,
        "cancellationRequestStatusCode": null,
        "cancelRefuseReason": null,
        "cancelReason": null,
        "amlDeclineReason": null,
        "amlMonitoringEnabled": null,
        "lastStatusRequestDate": null,
        "residencyCountryCode": "FI",
        "counterpartyOriginalIban": null,
        "fxPaymentFlag": false,
        "fxPayment": null,
        "paymentParties": [
            {
                "paymentPartyId": "PAYM-57267",
                "typeCode": "COUNTERPARTY",
                "name": "Robert Receiver",
                "personTypeCode": null,
                "givenName": null,
                "surname": null,
                "accountNumber": {
                    "value": "231123456789",
                    "type": "BBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "US",
                "financialInstitutionId": {
                    "value": "021000322",
                    "type": "ABA_CODE"
                },
                "address": null,
                "roleCode": "BENEFICIARY",
                "partyIdentification": null
            },
            {
                "paymentPartyId": "PAYM-57268",
                "typeCode": "OUR_PARTY",
                "name": "Test User",
                "personTypeCode": "P",
                "givenName": "Test",
                "surname": "User",
                "accountNumber": {
                    "value": "DK9189000021824474",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "DK",
                "financialInstitutionId": {
                    "value": "SXPYDKKK",
                    "type": "BIC"
                },
                "address": {
                    "street1": "",
                    "street2": null,
                    "cityCounty": "Tallinn",
                    "stateRegion": null,
                    "zip": null,
                    "countryCode": "EE",
                    "addressLine": "Maakri, Tallinn, EE",
                    "addressTypeCode": null
                },
                "roleCode": "PAYER",
                "partyIdentification": {
                    "identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
                    "identificationValue": "EE1234567"
                }
            }
        ],
        "fees": [],
        "paymentSchemeElements": [],
        "fileImportLineNumber": null,
        "purposeCode": null,
        "labels": [
            "COUNTERPARTY_US"
        ]
    }
}

Result

The draft payment has been created with a paymentId: PAYM-21726 and the statusCode: INSERTED.

Possible next steps

After creating a draft payment, you have the following options:

Change the draft payment - modify the draft payment.
Cancel the draft payment - discard the draft payment if it is no longer required.
Confirm the draft payment - complete payment to initiate further payment processing.

Create SEPA payment

Use case

In this scenario, we will create an outgoing SEPA payment - ACC2SEPA payment type.

Use case data

API parameters with values

Our party details gives the information about the sender of the payment. In this example, the payment is initialised from the Tuum account ID-4184.

Counterparty details.

Payment amount and currency.

Payment details.

The payment also includes payment steering data, such as valueDate and ourFee. Note: the valueDate and ourFee parameters are optional.

Sample API call

To initialise the payment, use the following endpoint:

https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise

Learn more about the initialise payment endpoint endpoint in the Tuum developer portal.

Sample request

The sample request body is as follows:

{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountId": "ID-4184"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "EE871275295834652820",
                "type": "IBAN"
            }
        }
    ],
    "money": {
        "amount": 25,
        "currencyCode": "EUR"
    },
    "details": "Test payment with our party accountId",
    "valueDate" : "2024-12-04",
    "ourFee": {
         "amount": 1.22,
         "currencyCode": "EUR"
  }
}

curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDRUMTQ6MjY6MTkiLCJleHAiOjE3MzMzMjIzNzksInJvbGVzIjpbIkFETUlOIl19.X1C4fpzVoXZnbicLPFW7izPPRLKGs-wGw6xoETGAypE' \
--header 'Content-Type: application/json' \
--data '{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountId": "ID-4184"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "EE871275295834652820",
                "type": "IBAN"
            }
        }
    ],
    "money": {
        "amount": 25,
        "currencyCode": "EUR"
    },
    "details": "Test payment with our party accountId",
    "valueDate" : "2024-12-04",
    "ourFee": {
         "amount": 1.22,
         "currencyCode": "EUR"
  }
}'

Sample response

Below you will find the response to the sample request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "paymentId": "PAYM-32706",
        "accountId": "ID-4184",
        "directionCode": "OUT",
        "statusCode": "INSERTED",
        "errorCode": null,
        "money": {
            "amount": 25.00,
            "currencyCode": "EUR"
        },
        "details": "Test payment with our party accountId",
        "referenceNumber": null,
        "source": null,
        "contractSource": null,
        "endToEndId": null,
        "valueDate": "2024-12-04",
        "postingDate": "2024-12-04",
        "insertedDateTime": "2024-12-04T13:28:52.498788Z",
        "paymentServiceProviderCode": "SEPA",
        "paymentTypeCode": "ACC2SEPA",
        "preferredPaymentScheme": null,
        "selectedPaymentScheme": "SEPA_INSTANT",
        "chargeBearer": null,
        "settlementStatusCode": null,
        "settlementErrorCode": null,
        "settlementDate": null,
        "settlementPaymentScheme": null,
        "returnStatusCode": null,
        "returnReason": null,
        "returnComment": null,
        "returnSettlementDate": null,
        "cancellationRequestStatusCode": null,
        "cancelRefuseReason": null,
        "cancelReason": null,
        "amlDeclineReason": null,
        "amlMonitoringEnabled": null,
        "lastStatusRequestDate": null,
        "residencyCountryCode": "GB",
        "counterpartyOriginalIban": null,
        "fxPaymentFlag": false,
        "fxPayment": null,
        "paymentParties": [
            {
                "paymentPartyId": "PAYM-67504",
                "typeCode": "COUNTERPARTY",
                "name": "Robert Receiver",
                "personTypeCode": null,
                "givenName": null,
                "surname": null,
                "accountNumber": {
                    "value": "EE871275295834652820",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "EE",
                "financialInstitutionId": {
                    "value": "PARXEE22XXX",
                    "type": "BIC"
                },
                "address": null,
                "roleCode": "BENEFICIARY",
                "partyIdentification": null
            },
            {
                "paymentPartyId": "PAYM-67505",
                "typeCode": "OUR_PARTY",
                "name": "Tuum Thomas",
                "personTypeCode": "P",
                "givenName": "Tuum",
                "surname": "Thomas",
                "accountNumber": {
                    "value": "XX20XXXX99999000000000000021075",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "XX",
                "financialInstitutionId": {
                    "value": "ICECLOUDXXX",
                    "type": "BIC"
                },
                "address": {
                    "street1": "24 Botley Road",
                    "street2": null,
                    "cityCounty": "Middleton Hall",
                    "stateRegion": null,
                    "zip": "NE71 3LL",
                    "countryCode": "GB",
                    "addressLine": "24 Botley Road, Middleton Hall, GB, NE71 3LL",
                    "addressTypeCode": null
                },
                "roleCode": "PAYER",
                "partyIdentification": {
                    "identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
                    "identificationValue": "DD654321C"
                }
            }
        ],
        "fees": [
            {
                "feeTypeCode": "ACC2SEPA_FEE",
                "feeMoney": {
                    "amount": 1.22,
                    "currencyCode": "EUR"
                },
                "deferredFee": false
            }
        ],
        "paymentSchemeElements": [],
        "fileImportLineNumber": null,
        "purposeCode": null,
        "labels": [
            "COUNTERPARTY_EE",
            "SEPA_INSTANT"
        ]
    }
}

Result

The draft payment has been created with a paymentId: PAYM-32706 and the statusCode: INSERTED.

Possible next steps

After creating a draft payment, you have the following options:

Change the draft payment - modify the draft payment.
Cancel the draft payment - discard the draft payment if it is no longer required.
Confirm the draft payment - complete payment to initiate further payment processing.

Create SWIFT payment

Use case

In this scenario, we will initialise an outgoing SWIFT (cross border) payment to a counterparty account with an IBAN and some sample data - ACC2SWIFT payment type.

Use case data

API parameters with values

Our party details gives the information about the sender of the payment. In this example, the payment is initialised from the Tuum account ID-1887.

Counterparty details.

Payment amount.

Payment details.

The payment also includes additional transferable data, such as chargeBearer and endToEndId. Note: the chargeBearer and endToEndId parameters are optional.

Sample API call

To initialise the payment, use the following endpoint:

https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise

Learn more about the initialise payment endpoint in the Tuum developer portal.

Sample request

The sample request body is as follows:

{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountId": "ID-21508"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Ben Eficiary",
            "accountNumber": {
                "value": "EE871275295834652820",
                "type": "IBAN"
            },
            "financialInstitutionId": "PARXEE22XXX",
            "address": {
                "street1": "First street 123",
                "street2": "Second street 321",
                "cityCounty": "Some city",
                "zip": "06777",
                "countryCode": "EE"
            }
        }
    ],
    "money": {
        "amount": 1,
        "currencyCode": "DKK"
    },
    "details": "Test payment",
    "endToEndId": "20240103-E000003",
    "chargeBearer": "DEBT"
}

curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDZUMTM6Mjc6MzUiLCJleHAiOjE3MzM0OTE2NTUsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.r4Efnh8m_waGXaTRBQDLhLDb2M6no_SRJpZCGPoO6K8' \
--header 'Content-Type: application/json' \
--data '{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountId": "ID-21508"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Ben Eficiary",
            "accountNumber": {
                "value": "EE871275295834652820",
                "type": "IBAN"
            },
            "financialInstitutionId": "PARXEE22XXX",
            "address": {
                "street1": "First street 123",
                "street2": "Second street 321",
                "cityCounty": "Some city",
                "zip": "06777",
                "countryCode": "EE"
            }
        }
    ],
    "money": {
        "amount": 1,
        "currencyCode": "DKK"
    },
    "details": "Test payment",
    "endToEndId": "20240103-E000003",
    "chargeBearer": "DEBT"
}'

Sample response

Below you will find the response to the sample request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "paymentId": "PAYM-21846",
        "accountId": "ID-21508",
        "directionCode": "OUT",
        "statusCode": "INSERTED",
        "errorCode": null,
        "money": {
            "amount": 1.00,
            "currencyCode": "DKK"
        },
        "details": "Test payment",
        "referenceNumber": null,
        "source": null,
        "contractSource": null,
        "endToEndId": "20240103-E000003",
        "valueDate": "2029-12-02",
        "postingDate": "2029-12-02",
        "insertedDateTime": "2024-12-06T12:41:45.629822Z",
        "paymentServiceProviderCode": "SWIFT",
        "paymentTypeCode": "ACC2SWIFT",
        "preferredPaymentScheme": null,
        "selectedPaymentScheme": null,
        "chargeBearer": "DEBT",
        "settlementStatusCode": null,
        "settlementErrorCode": null,
        "settlementDate": null,
        "settlementPaymentScheme": null,
        "returnStatusCode": null,
        "returnReason": null,
        "returnComment": null,
        "returnSettlementDate": null,
        "cancellationRequestStatusCode": null,
        "cancelRefuseReason": null,
        "cancelReason": null,
        "amlDeclineReason": null,
        "amlMonitoringEnabled": null,
        "lastStatusRequestDate": null,
        "residencyCountryCode": "EE",
        "counterpartyOriginalIban": null,
        "fxPaymentFlag": false,
        "fxPayment": null,
        "paymentParties": [
            {
                "paymentPartyId": "PAYM-57584",
                "typeCode": "COUNTERPARTY",
                "name": "Ben Eficiary",
                "personTypeCode": null,
                "givenName": null,
                "surname": null,
                "accountNumber": {
                    "value": "EE871275295834652820",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "EE",
                "financialInstitutionId": {
                    "value": "PARXEE22XXX",
                    "type": "BIC"
                },
                "address": {
                    "street1": "First street 123",
                    "street2": "Second street 321",
                    "cityCounty": "Some city",
                    "stateRegion": null,
                    "zip": "06777",
                    "countryCode": "EE",
                    "addressLine": "First street 123, Second street 321, Some city, EE, 06777",
                    "addressTypeCode": null
                },
                "roleCode": "BENEFICIARY",
                "partyIdentification": null
            },
            {
                "paymentPartyId": "PAYM-57585",
                "typeCode": "OUR_PARTY",
                "name": "Test Payer",
                "personTypeCode": "P",
                "givenName": null,
                "surname": null,
                "accountNumber": {
                    "value": "XX46XXXX99999000000000000111011",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "XX",
                "financialInstitutionId": {
                    "value": "ICECLOUDXXX",
                    "type": "BIC"
                },
                "address": {
                    "street1": "Tartu mnt 32-25",
                    "street2": null,
                    "cityCounty": "Harjumaa",
                    "stateRegion": "Tallinn",
                    "zip": "10115",
                    "countryCode": "EE",
                    "addressLine": "Tartu mnt 32-25, Harjumaa, EE, 10115",
                    "addressTypeCode": null
                },
                "roleCode": "PAYER",
                "partyIdentification": {
                    "identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
                    "identificationValue": "314-494-5904"
                }
            }
        ],
        "fees": [],
        "paymentSchemeElements": [],
        "fileImportLineNumber": null,
        "purposeCode": null,
        "labels": [
            "COUNTERPARTY_EE"
        ]
    }
}

Result

The draft payment has been created with a paymentId: PAYM-21846 and the statusCode: INSERTED.

Possible next steps

After creating a draft payment, you have the following options:

Change the draft payment - modify the draft payment.
Cancel the draft payment - discard the draft payment if it is no longer required.
Confirm the draft payment - complete payment to initiate further payment processing.

Create domestic UK payment

Here, you can find one of the examples of how to create a draft payment using the .

Use case

In this scenario, we will create a domestic UK payment from Tuum BC (Banking Circle) UK account to another UK account. In this case, the payment will be created with the ACC2LOCAL payment type.

Use case data

API parameters with values

Our party details give the information about the sender of the payment. In this example, the payment is initialised from the Tuum bank account with 21824474 BBAN.

The payer's account country is the UK. Note: the payer's bank account financial institution id is the bank's sort code.

Counterparty details.

The payment receiver account country is the UK. Note: the payment receiver financial institution id is the bank's sort code.

Payment amount and currency.

Payment details.

The payment also includes non-transferrable data, such as contractSource. Note: the contractSource parameter is optional.

Sample API call

To initialise the payment, use the following endpoint: https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise

Learn more about the initialise payment endpoint endpoint in the Tuum developer portal.

Sample request

The sample request body is as follows:

{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountNumber": {
                "value": "21824474",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "608382"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "00001781",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "040300"
        }
    ],
    "money": {
        "amount": 15,
        "currencyCode": "GBP"
    },
    "details": "Test payment with both parties with BBAN for domestic UK payment",
    "contractSource": {
    "sourceName": "Test System",
    "sourceRef": "1234",
    "contractNumber": "test"
  }
}

curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDVUMTM6MTA6MDciLCJleHAiOjE3MzM0MDQyMDcsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.T2c1I6mazgGm2gT6p3lqaXxb2qj9OTPiluP5XnJr0zU' \
--header 'Content-Type: application/json' \
--data '{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountNumber": {
                "value": "21824474",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "608382"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "00001781",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "040300"
        }
    ],
    "money": {
        "amount": 15,
        "currencyCode": "GBP"
    },
    "details": "Test payment with both parties with BBAN for domestic UK payment",
    "contractSource": {
    "sourceName": "Test System",
    "sourceRef": "1234",
    "contractNumber": "test"
  }
}'

Sample response

Below you will find the response to the sample request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "paymentId": "PAYM-21826",
        "accountId": "ID-17598",
        "directionCode": "OUT",
        "statusCode": "INSERTED",
        "errorCode": null,
        "money": {
            "amount": 15.00,
            "currencyCode": "GBP"
        },
        "details": "Test payment with both parties with BBAN for domestic UK payment",
        "referenceNumber": null,
        "source": null,
        "contractSource": {
            "sourceName": "Test System",
            "sourceRef": "1234",
            "contractNumber": "test"
        },
        "endToEndId": null,
        "valueDate": "2029-11-27",
        "postingDate": "2029-11-27",
        "insertedDateTime": "2024-12-05T12:21:07.149343Z",
        "paymentServiceProviderCode": "BC",
        "paymentTypeCode": "ACC2LOCAL",
        "preferredPaymentScheme": null,
        "selectedPaymentScheme": null,
        "chargeBearer": null,
        "settlementStatusCode": null,
        "settlementErrorCode": null,
        "settlementDate": null,
        "settlementPaymentScheme": null,
        "returnStatusCode": null,
        "returnReason": null,
        "returnComment": null,
        "returnSettlementDate": null,
        "cancellationRequestStatusCode": null,
        "cancelRefuseReason": null,
        "cancelReason": null,
        "amlDeclineReason": null,
        "amlMonitoringEnabled": null,
        "lastStatusRequestDate": null,
        "residencyCountryCode": "FI",
        "counterpartyOriginalIban": null,
        "fxPaymentFlag": false,
        "fxPayment": null,
        "paymentParties": [
            {
                "paymentPartyId": "PAYM-57538",
                "typeCode": "COUNTERPARTY",
                "name": "Robert Receiver",
                "personTypeCode": null,
                "givenName": null,
                "surname": null,
                "accountNumber": {
                    "value": "00001781",
                    "type": "BBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "GB",
                "financialInstitutionId": {
                    "value": "040300",
                    "type": "SORT_CODE"
                },
                "address": null,
                "roleCode": "BENEFICIARY",
                "partyIdentification": null
            },
            {
                "paymentPartyId": "PAYM-57539",
                "typeCode": "OUR_PARTY",
                "name": "Daria Core",
                "personTypeCode": "P",
                "givenName": "Daria",
                "surname": "Core",
                "accountNumber": {
                    "value": "DK9189000021824474",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "DK",
                "financialInstitutionId": {
                    "value": "SXPYDKKK",
                    "type": "BIC"
                },
                "address": {
                    "street1": "Maakri",
                    "street2": null,
                    "cityCounty": "Tallinn",
                    "stateRegion": null,
                    "zip": null,
                    "countryCode": "EE",
                    "addressLine": "Maakri, Tallinn, EE",
                    "addressTypeCode": null
                },
                "roleCode": "PAYER",
                "partyIdentification": {
                    "identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
                    "identificationValue": "EE1234567"
                }
            }
        ],
        "fees": [],
        "paymentSchemeElements": [],
        "fileImportLineNumber": null,
        "purposeCode": null,
        "labels": [
            "COUNTERPARTY_GB"
        ]
    }
}

Result

The draft payment has been created with a paymentId: PAYM-21826 and the statusCode: INSERTED.

Possible next steps

After creating a draft payment, you have the following options:

Change the draft payment - modify the draft payment.
Cancel the draft payment - discard the draft payment if it is no longer required.
Confirm the draft payment - complete payment to initiate further payment processing.

Create domestic US payment

Here, you can find one of the examples of how to create a draft payment using the .

Use case

In this scenario, we will create a domestic US payment - ACC2LOCAL payment type.

Use case data

API parameters with values

Our party details gives the information about the sender of the payment. In this example, the payment is initialised from the Tuum bank account with 190021824474 BBAN.

The payer's account country is the USA. Note: the payer's bank account financial institution id is the ABA Routing number.

Counterparty details.

The payer's account country is the USA. Note: the payer's bank account financial institution id is the ABA Routing number.

Payment amount and currency.

Payment details.

The payment also includes payment steering data, such as usageLimitCode. Note: the usageLimitCode is an optional parameter.

Sample API call

To initialise the payment, use the following endpoint: https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise

Learn more about the initialise payment endpoint endpoint in the Tuum developer portal.

Sample request

The sample request body is as follows:

{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountNumber": {
                "value": "190021824474",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "US",
            "financialInstitutionId": "021000018"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "231123456789",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "US",
            "financialInstitutionId": "021000322"
        }
    ],
    "money": {
        "amount": 17,
        "currencyCode": "USD"
    },
    "details": "Test payment with both parties with BBAN for domestic US payment",
    "usageLimitCode": "test"
}

curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/initialise' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTItMDVUMTM6NDM6MTAiLCJleHAiOjE3MzM0MDYxOTAsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.03a1hgsWy3yZxxKXl-TpIatf4XAllaA0dquZH4U8a0E' \
--header 'Content-Type: application/json' \
--data '{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountNumber": {
                "value": "190021824474",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "US",
            "financialInstitutionId": "021000018"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Robert Receiver",
            "accountNumber": {
                "value": "231123456789",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "US",
            "financialInstitutionId": "021000322"
        }
    ],
    "money": {
        "amount": 17,
        "currencyCode": "USD"
    },
    "details": "Test payment with both parties with BBAN for domestic US payment",
    "usageLimitCode": "test"
}'

Sample response

Below you will find the response to the sample request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": {
        "paymentId": "PAYM-21726",
        "accountId": "ID-17598",
        "directionCode": "OUT",
        "statusCode": "INSERTED",
        "errorCode": null,
        "money": {
            "amount": 17.00,
            "currencyCode": "USD"
        },
        "details": "Test payment with both parties with BBAN for domestic US payment",
        "referenceNumber": null,
        "source": null,
        "contractSource": null,
        "endToEndId": null,
        "valueDate": "2029-11-01",
        "postingDate": "2029-11-01",
        "insertedDateTime": "2024-11-28T16:09:32.4368Z",
        "paymentServiceProviderCode": "BC",
        "paymentTypeCode": "ACC2LOCAL",
        "preferredPaymentScheme": null,
        "selectedPaymentScheme": null,
        "chargeBearer": null,
        "settlementStatusCode": null,
        "settlementErrorCode": null,
        "settlementDate": null,
        "settlementPaymentScheme": null,
        "returnStatusCode": null,
        "returnReason": null,
        "returnComment": null,
        "returnSettlementDate": null,
        "cancellationRequestStatusCode": null,
        "cancelRefuseReason": null,
        "cancelReason": null,
        "amlDeclineReason": null,
        "amlMonitoringEnabled": null,
        "lastStatusRequestDate": null,
        "residencyCountryCode": "FI",
        "counterpartyOriginalIban": null,
        "fxPaymentFlag": false,
        "fxPayment": null,
        "paymentParties": [
            {
                "paymentPartyId": "PAYM-57267",
                "typeCode": "COUNTERPARTY",
                "name": "Robert Receiver",
                "personTypeCode": null,
                "givenName": null,
                "surname": null,
                "accountNumber": {
                    "value": "231123456789",
                    "type": "BBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "US",
                "financialInstitutionId": {
                    "value": "021000322",
                    "type": "ABA_CODE"
                },
                "address": null,
                "roleCode": "BENEFICIARY",
                "partyIdentification": null
            },
            {
                "paymentPartyId": "PAYM-57268",
                "typeCode": "OUR_PARTY",
                "name": "Test User",
                "personTypeCode": "P",
                "givenName": "Test",
                "surname": "User",
                "accountNumber": {
                    "value": "DK9189000021824474",
                    "type": "IBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "DK",
                "financialInstitutionId": {
                    "value": "SXPYDKKK",
                    "type": "BIC"
                },
                "address": {
                    "street1": "",
                    "street2": null,
                    "cityCounty": "Tallinn",
                    "stateRegion": null,
                    "zip": null,
                    "countryCode": "EE",
                    "addressLine": "Maakri, Tallinn, EE",
                    "addressTypeCode": null
                },
                "roleCode": "PAYER",
                "partyIdentification": {
                    "identificationTypeCode": "NATIONAL_IDENTIFICATION_NUMBER",
                    "identificationValue": "EE1234567"
                }
            }
        ],
        "fees": [],
        "paymentSchemeElements": [],
        "fileImportLineNumber": null,
        "purposeCode": null,
        "labels": [
            "COUNTERPARTY_US"
        ]
    }
}

Result

The draft payment has been created with a paymentId: PAYM-21726 and the statusCode: INSERTED.

Possible next steps

After creating a draft payment, you have the following options:

Change the draft payment - modify the draft payment.
Cancel the draft payment - discard the draft payment if it is no longer required.
Confirm the draft payment - complete payment to initiate further payment processing.