Skip to main content

Change amount

Learn how to use the Dojo Payments API to update payment.

You can use the Payments API to alter configurable fields, including the payment and tip amount, after creating the payment intent. Before you start, make sure that you have a payment intent that can be updated. By default, payment intents are unalterable and can't be updated. If you want to be able to update the payment, you must include config fields when creating the payment intent. These config fields should indicate which updates are allowed. In the following example, both the payment amount and the tip amount can be changed:

"config": {
    "payment": {
        "customAmountAllowed": true,
        "tipsAllowed": true
    }
}

When the payment amount is changed, a new clientSessionSecret is generated. If previously generated, the old access token becomes invalid for payment processing. You must use the latest clientSessionSecret after any amount changes to complete the payment.

You can only change an amount for payments before it has been captured.

Change payment amount​

To change a payment amount, use the endpoint below:

POST /payment-intents/{paymentIntentId}/amount

In your request, include:

  • paymentIntentId: This identifies the specific payment intent.

  • amount: This is the new amount to be collected by this payment intent.

For the full API specification, see the reference.

Request example​

The next example below shows how you would change the payment amount by 10.00 GBP.

# The sandbox API key passed in 'authorization' is public.
# Don't submit any personally identifiable information in any requests made with this key.
# Sign in to developer.dojo.tech to create your own private sandbox key and use that instead
# for secure testing.

curl -v --request POST \
  --url https://api.dojo.tech/payment-intents/<paymentIntentId> \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <your_api_key>' \
  --header 'Version: 2024-02-05' \
  --data '{
    "amount": {
      "value": 1000,
      "currencyCode": "GBP"
    }
}'

Response example​

If your request is successful, the response will return information about the changed payment intent.

{
  "id": "pi_pT08VyWG3EC_HQB4NBVliA",
  "captureMode": "Auto",
  "clientSessionSecret": "string",
  "clientSessionSecretExpirationDate": "2019-08-24T14:15:22Z",
  "status": "Created",
  "paymentMethods": [
    "Card"
  ],
  "amount": {
    "value": 1000,
    "currencyCode": "GBP"
  },
  "tipsAmount": {
    "value": 0,
    "currencyCode": "string"
  },
  "requestedAmount": {
    "value": 0,
    "currencyCode": "string"
  },
  "totalAmount": {
    "value": 1000,
    "currencyCode": "string"
  },
  "reference": "string",
  "config": {
    "title": "string",
    "redirectUrl": "http://example.com",
    "cancelUrl": "http://example.com",
    "customerEmail": {
      "collectionRequired": false
    },
    "details": {
      "showTotal": true,
      "showReference": true
    },
    "billingAddress": {
      "collectionRequired": true
    },
    "shippingDetails": {
      "collectionRequired": true
    },
    "payment": {
      "customAmountAllowed": true,
      "tipsAllowed": true
    }
  }
}

Change tip amount​

To change a tip amount, use the endpoint below:

POST /payment-intents/{paymentIntentId}/tips-amount

In your request, include:

  • paymentIntentId: identifies the payment being changed.

  • tipsAmount: the tips amount.

For the full specification, see the API reference.

Request example​

The next example below shows how you would change the tip's amount by 2.00 GBP.

# The sandbox API key passed in 'authorization' is public.
# Don't submit any personally identifiable information in any requests made with this key.
# Sign in to developer.dojo.tech to create your own private sandbox key and use that instead
# for secure testing.

curl -v --request POST \
  --url https://api.dojo.tech/payment-intents/<paymentIntentId> \
  --header 'Content-Type: application/json' \
  --header 'IdempotencyKey: 656565gfyd65' \
  --header 'Authorization: Basic <your_api_key>' \
  --header 'Version: 2024-02-05' \
  --data '{
    "tipsAmount": {
      "value": 200,
      "currencyCode": "GBP"
    }
}'

Response example​

If your request is successful, the response will return information about the changed payment intent. Here, you can see that the tipsAmount is now 200, whereas in the original response body it was 0.

{
  "id": "pi_pT08VyWG3EC_HQB4NBVliA",
  "captureMode": "Auto",
  "clientSessionSecret": "string",
  "clientSessionSecretExpirationDate": "2019-08-24T14:15:22Z",
  "status": "Created",
  "paymentMethods": [
    "Card"
  ],
  "amount": {
    "value": 1000,
    "currencyCode": "GBP"
  },
  "tipsAmount": {
    "value": 200,
    "currencyCode": "GBP"
  },
  "requestedAmount": {
    "value": 0,
    "currencyCode": "string"
  },
  "totalAmount": {
    "value": 1200,
    "currencyCode": "string"
  },
  "reference": "string",
  "payment": {
    "customAmountAllowed": true,
    "tipsAllowed": true
  }
}

Change request fails​

If a request fails, the unmodified payment intent can still be completed. If you want to increase the payment or tips amount, you might consider alternative options:

  • Capture the unmodified payment intent, then create a new payment intent to pay the additional amount.

  • Create a new payment intent with the same payments details, but with a new amount. After the payment intent is captured, cancel the original payment intent.

Last updated on