<!-- LLM_VERSION_INFO
FORMAT: text/markdown
CONTENT_TYPE: article
ORIGINAL_URL: https://www.carbon.money/docs-sub/docs/custom-term-url
ALTERNATE_VERSION: docs-sub/docs/custom-term-url/index.html (text/html)
EXTRACTION_DATE: 2026-06-11T01:52:31.822Z

This is the markdown version with text-only content (images converted to alt-text).
For rich formatting with images, request the HTML version at: docs-sub/docs/custom-term-url/index.html
-->

As you may recall from the [Credit/Debit Purchases API](/content/docs/credit-debit/index.html) page, the response to your `/v1/card/charge3d` POST request includes a `termurl` for 3D Secure enrolled cards.

This URL is used as part of the form submission to the card issuer Access Control Server (ACS) where the cardholder's identity is verified, as we covered in our [3D Secure Card Payments Overview](/content/docs/3d-secure-card-payments/index.html).

Following verification, the ACS sends a POST request to the Term URL with the necessary information for the card to be charged and for the transaction to be processed.

### Carbon provides the Term URL in most cases

This way, less development is required by you, the integrator.

## _We now provide the option of providing your own Term URL (required for payment gateway)_

### Providing your own Term URL gives you more freedom to control the end user purchase flow

Please contact [\[email protected\]](/#254f4a404965464457474a4b0b484a4b405c) for more information.

# Setting Superuser Term URL

## Example request/response

- [Javascript](/content/docs-sub/docs/custom-term-url/index.html)
- [Success (200)](/content/docs-sub/docs/custom-term-url/index.html)
- [Errors](/content/docs-sub/docs/custom-term-url/index.html)

```
// legacy auth that will be deprecated in our v2 api
/*
let jwtToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJlMzE3YjdlNy0yMzQ1LTQ0MWMtODA0Ni1kYjgxNTkyYmEyN2YiLCJzdXBlclVzZXIiOnRydWUsImNvbnRhY3QiOmZhbHNlLCJlbWFpbCI6ImRhbmllbEBjYXJib24ubW9uZXkiLCJpYXQiOjE1NTczMjc5MTR9.WZnSR5N1FebmT9nMu97PJvku49NY0jk4aKVPKm_1MlM';
*/
// we strongly recommend using your secret key to more securely authenticate your superuser instead
let secretKey = 'sk_test_A41Hm6IY3Q5LJ7ham34Zpkcj';
let headers = {
  headers: {
    Authorization: `Bearer ${secretKey}`
  }
};
let url = `${ROOT}/v1/admin`;
let data = {
  termUrl: 'https://sandbox.carbon.money/termUrl',
}
axios.put(url, data, headers).then(result => console.log(result)).catch(err => console.log(err));
```

# Getting Superuser Term URL

# Requirements for Term URL

- MUST check for `PaRes` and `MD` in the request body (case- **sensitive**)
- MUST call either `/v1/card/charge3d/auth` or `/v1/card/charge3d/auth/cancel` before sending a response
- MUST handle errors from `/v1/card/charge3d/auth` as detailed in the section below
- MUST complete the delivery of the asset following a successful charge
- MUST notify Carbon of the completion of the purchase using `/v1/card/charge3d/auth/complete`
- SHOULD notify the user of the completion of the purchase

When the purchase is completed, the response that your Term URL sends will be rendered in your front end, or you can redirect to a different route.

# Authorization (charging the user's card)

## Example request/response

- [JavaScript](/content/docs-sub/docs/custom-term-url/index.html)
- [Success (200) (Card charged)](/content/docs-sub/docs/custom-term-url/index.html)
- [Success (200) (Card not charged)](/content/docs-sub/docs/custom-term-url/index.html)
- [Errors](/content/docs-sub/docs/custom-term-url/index.html)

Params

| Access      | Description                                                  |
|-------------|--------------------------------------------------------------|
| MD          | Required                                                    |
| PaRes       | Required                                                    |

## Error Handling

In the case that you receive a `200` response with `success:false` in the body, you can display the error log (or your own message) to the user for them to resolve the issue. This is most likely fixed by the user double checking their card information, or contacting their bank, which may have blocked the charge.

# Next steps...

Once you have received confirmation the user's card has been charged, it is your responsibility to deliver their assets and then **confirm with Carbon that the purchase is completed** using the `/v1/card/charge3d/auth/complete` route.

### You must confirm the completion of every purchase

If we do not receive a confirmation that the purchase has been filled, we will cancel the charge on the card without warning. You will have up to 6 hours to send the confirmation.

We understand that errors happen, but if an error occurs in the delivery of the goods to the user we need to cancel the charge on the user's card as soon as possible. You can cancel the charge with the `/v1/card/charge3d/auth/cancel` route.

After a charge has settled (~24 hours after the initial authorization), a cancellation cannot be processed. If a user contests a charge or needs to be refunded for some reason after this window, you can use `/v1/card/charge3d/auth/refund` to process a refund.

## Completing the purchase _(example)_

- [JavaScript](/content/docs-sub/docs/custom-term-url/index.html)

Params

| Access    | Description                                                  |
|-----------|--------------------------------------------------------------|
| MD        | Required                                                    |
| transactionHash | Required                                       |

## Cancellations and Refunds

_Cancellation example_

- [JavaScript](/content/docs-sub/docs/custom-term-url/index.html)

Params

| Access | Description                                                  |
|--------|--------------------------------------------------------------|
| MD     | Required                                                    |

### Charges that have already settled cannot be cancelled

If the charge has a status of `100`, the charge has settled and must be refunded, not cancelled.

_Refund example_

### Refunds incur a small fee

Your first 10 refunds each month are free, each additional refund will incur a fee of $1.25 subtracted from your settled volume. We do not make a profit on refunds.

- [JavaScript](/content/docs-sub/docs/custom-term-url/index.html)

Params

| Access | Description                                                  |
|--------|--------------------------------------------------------------|
| MD     | Required                                                    |