Change payment

Use case

In this example, we will review how to change a payment draft. We will update counterparty and payment amount.

Use case data	API parameters with values
We are going to update the PAYM-21826 payment.	...v3/payments/PAYM-21826/change
Payer information. In this example, the payer details remained the same as in the original request.	{ "typeCode": "OUR_PARTY", "accountNumber": { "value": "21824474", "type": "BBAN" }, "accountNumberCountryCode": "GB", "financialInstitutionId": "608382" }
Updated counterparty details. The counterparty name, account information, and financial institution id were updated.	{ "typeCode": "COUNTERPARTY", "name": "Test Receiver", "accountNumber": { "value": "56497232", "type": "BBAN" }, "accountNumberCountryCode": "GB", "financialInstitutionId": "BARCGB22" }
Updated payment amount.	"money": { "amount": 20, "currencyCode": "GBP" }

Sample API call

To change the payment, use the following endpoint: https://payment-api.sandbox.tuumplatform.com/api/v3/payments/{paymentId}/change

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

Sample request

The sample request body is as follows:

JSON

{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountNumber": {
                "value": "21824474",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "608382",
            },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Test Receiver",
            "accountNumber": {
                "value": "56497232",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "BARCGB22"
        }
    ],
    "money": {
        "amount": 20,
        "currencyCode": "GBP"
    }
    }

cURL

curl --location 'https://payment-api.sandbox.tuumplatform.com/api/v3/payments/PAYM-21777/change' \
--header 'x-channel-code: SYSTEM' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiSm9obiBPZmZpY2VyIiwiZW1wbG95ZWVJZCI6IjEiLCJ0ZW5hbnRDb2RlIjoiTUIiLCJleHBpcnlEVGltZSI6IjIwMjQtMTEtMzBUMDI6NDc6MjYiLCJleHAiOjE3MzI5MzQ4NDYsInJvbGVzIjpbIkFETUlOIiwiUE9TVElOR1NfVEVBTSJdfQ.aZQf-Tf3Zro6Ri6_FD-izuqQ37MoDJKJmISkWeDyzSo' \
--header 'Content-Type: application/json' \
--data '{
    "paymentParties": [
        {
            "typeCode": "OUR_PARTY",
            "accountNumber": {
                "value": "21824474",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "608382"
        },
        {
            "typeCode": "COUNTERPARTY",
            "name": "Test Receiver",
            "accountNumber": {
                "value": "56497232",
                "type": "BBAN"
            },
            "accountNumberCountryCode": "GB",
            "financialInstitutionId": "BARCGB22"
        }
    ],
    "money": {
        "amount": 20,
        "currencyCode": "GBP"
    }
    }'

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": 20.00,
            "currencyCode": "GBP"
        },
        "details": null,
        "referenceNumber": null,
        "source": null,
        "contractSource": null,
        "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-57542",
                "typeCode": "COUNTERPARTY",
                "name": "Test Receiver",
                "personTypeCode": null,
                "givenName": null,
                "surname": null,
                "accountNumber": {
                    "value": "56497232",
                    "type": "BBAN"
                },
                "accountNumberSubtype": null,
                "accountNumberCountryCode": "GB",
                "financialInstitutionId": {
                    "value": "BARCGB22",
                    "type": "BIC"
                },
                "address": null,
                "roleCode": "BENEFICIARY",
                "partyIdentification": null
            },
            {
                "paymentPartyId": "PAYM-57543",
                "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 payment draft with the paymentId: PAYM-21826 was updated. The payment status remained as INSERTED.

Possible next steps

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

1. Change the draft payment - modify the draft payment.

2. Confirm the draft payment - complete payment to initiate further payment processing.

3. Cancel the draft payment - discard the draft payment if it is no longer required.