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 the customer authorizes the payment, updates are controlled by the payment intent's config fields. By default, payment intents are unalterable and can't be updated. In the following example, both the payment amount and the tip amount can be changed:

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

When you change the amount before authorization, a new clientSessionSecret is generated. If previously generated, the old access token becomes invalid for payment processing. You must use the latest clientSessionSecret to complete the payment. The incremental pre-authorization flow described below does not generate or require a new client session secret.

You can change an amount before it has been captured. After authorization, the available amount-change behavior depends on the payment flow.

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>/amount' \
  --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
    }
  }
}

Increase an authorized amount​

For eligible online pre-authorizations, you can increase the authorized amount after the customer has authorized the payment and before you capture it. This is called incremental pre-authorization and is useful when the final total is not known at the time of authorization.

This is a separate flow from changing an amount before authorization. It applies to payment intents with captureMode: Manual and status: Authorized that were created through the Virtual Terminal online flow. It does not require customAmountAllowed and does not refresh the client session secret. Availability depends on the Dojo merchant account, merchant category, card scheme, and feature rollout. Supported card schemes are Visa, Mastercard, American Express, and Discover.

Use the same endpoint, but send the new total authorized amount, not the amount to add. For example, if the current authorization is GBP 50.00, send GBP 80.00 to request an increase of GBP 30.00:

POST /payment-intents/{paymentIntentId}/amount

{
  "amount": {
    "value": 8000,
    "currencyCode": "GBP"
  }
}

The amount is expressed in the currency's minor units. You can request further increases before capture. A request for the current total is a no-op; a lower total is rejected. Up to 10 successful increases are allowed, and the resulting authorized total cannot exceed five times the original authorization. The issuer or scheme can still decline an increase.

If an increase is approved, the payment intent response contains the resulting authorized amount. If it is not approved, the payment intent amount is not updated. You can then capture all or part of the updated authorized amount.

note

Incremental pre-authorization is not available for every merchant or payment. Contact Dojo to confirm eligibility for your account.

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