1 of 1

Create domestic US payment

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

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:

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.

{
  "typeCode": "OUR_PARTY",
  "accountNumber": {
       "value": "190021824474",
       "type":
            }

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

"accountNumberCountryCode": "US",
"financialInstitutionId": "021000018"

Counterparty details.

"typeCode": "COUNTERPARTY",
"name": "Robert Receiver",
"accountNumber": {
     "value": "231123456789",
     "type": "BBAN"

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

"accountNumberCountryCode": "US",
"financialInstitutionId": "021000322"

Payment amount and currency.

 "money": {
        "amount": 17,
        "currencyCode": "USD"
    }

Payment details.

"details": "Test payment with both parties with BBAN for domestic US payment"

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

 "usageLimitCode": "test"

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 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:

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