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

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.

manage-payments/curl/change-amount.sh
loading...

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": 0,
    "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.

manage-payments/curl/change-tips-amount.sh
loading...

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": 0,
    "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