Last Updated: 30 April 2024 | Change Log

Manage payments

Warning

This documentation is for version 7 of the Card Payments API. You can find the "Manage Payments" documentation for version 6 in our archive. You can find information on how to upgrade in our migration guide.

This document gives an overview on how to cancel, settle, refund or reverse payments.

Best Practice

To manage your payments we recommend using our events service to receive the latest status of your payment to your server in real-time.

Cancel an authorization

If you don't want to proceed with a payment, you can send a cancel request.

POST to the cardPayments:cancel action link, returned in any of your authorization responses, to cancel the authorization.

Note

You can only cancel a payment which is authorized. If the payment is settled, you must create a refund.

Cancel request

POST https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiJ9

Note

No request body is needed for this request.

Cancel response

In the response you get a 202 HTTP code which confirms we have received your request. The request has not processed at this stage. You must query the payment to check the status. You can find a link for this in the response body.

Best Practice

If you're using our events service, as per our best practice, you should already have the latest payment status.

{
    "_links": {
        "cardPayments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [
            {
                "name": "cardPayments",
                "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}",
                "templated": true
            }
        ]
    }
}

Settle an authorization

To receive all the funds from the customer, send us a settle request.

You can only do this, if you set "requestAutoSettlement" to false in your initial request.

POST to the cardPayments:settle action link, returned in any of the authorization responses, to settle an authorization.

Settle request

POST https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiJ9

Note

No request body is needed for this request.

Marketplaces can optionally provide a body containing marketplace data for settlement requests:

{
    "merchant": {
        "marketplace": {
            "sellerCountryCode": "GB",
            "splitFundingReference": "Your split funding reference"
        }
    }
}

When you make your settle request, the payment event changes to sentForSettlement.

Settle response

In the response you get a 202 HTTP code which confirms we have received your request. The request has not processed at this stage. You must query the payment to check the status. You can find a link for this in the response body, as well as links to refund and partially refund.

Best Practice

If you're using our events service, as per our best practice, you should already have the latest payment status.

{
    "_links": {
        "cardPayments:refund": {
            "href": "https://try.access.worldpay.com/payments/settlements/refunds/full/eyJrIjoiazNhYjYzMiJ9"
        },
        "cardPayments:partialRefund": {
            "href": "https://try.access.worldpay.com/payments/settlements/refunds/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "cardPayments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [
            {
                "name": "cardPayments",
                "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}",
                "templated": true
            }
        ]
    }
}


Partially settle an authorization

To receive a portion of the funds of a payment, send us a request to partially settle an authorization.

You can only do this, if you set "requestAutoSettlement" to false in your initial request.

POST to the cardPayments:partialSettle action link, returned in your authorization response, to partially settle an authorization. Specify the amount and the required settlement currency in the body.

Note

We do not validate that the currency and amount is the same as the original payment.

Partial settle request

POST https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiJ9

  1. Standard
  2. Marketplace

{% code-snippet file="./code/manage-payments/partial-settlement.json language="json" /%}

Descriptions of your partial settlement request parameters:

ParameterRequiredDescription
referenceA unique reference generated by you to identify the partial settlement. For more information and best practice see transaction reference format.
sequence.numberRequired if supplying marketplace data. Else, optional.The sequence number for this request for partial settlement. Eg sequence number 1 of 2 total partial settlement requests.
sequence.totalRequired if supplying marketplace data. Else, optional.The total number of expected partial settlement requests.

Partial settle response

In the response you get a 202 HTTP code which confirms we have received your request. The request has not processed at this stage. You must query the payment to check the status. You can find a link for this in the response body, as well as links to refund, partially refund, partially settle and cancel your payment.

Best Practice

If you're using our events service, as per our best practice, you should already have the latest payment status.

{
    "_links": {
        "cardPayments:refund": {
            "href": "https://try.access.worldpay.com/payments/settlements/refunds/full/eyJrIjoiazNhYjYzMiJ9"
        },
        "cardPayments:partialRefund": {
            "href": "https://try.access.worldpay.com/payments/settlements/refunds/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "cardPayments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "cardPayments:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiJ9"
        },
        "cardPayments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [{
            "name": "cardPayments",
            "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}",
            "templated": true
        }]
    }
}


Fully refund a payment

Send a refund request to return the full settled amount to your customer.

POST to the cardPayments:refund action link received in your full settlement, partial settlement or customerInitiatedTransactions response (where you have requested auto settlement).

Full refund request

POST https://try.access.worldpay.com/payments/settlements/refunds/full/eyJrIjoiazNhYjYzMiJ9

Note

No request body is needed for this request.

Full refund response

In the response you get a 202 HTTP code which confirms we have received your request. The request has not processed at this stage. You must query the payment to check the status. You can find a link for this in the response body.

Best Practice

If you're using our events service, as per our best practice, you should already have the latest payment status.

{
    "_links": {
        "cardPayments:events": {
            "href": "https://access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [
            {
                "name": "cardPayments",
                "href": "https://access.worldpay.com/rels/cardPayments/{rel}",
                "templated": true
            }
        ]
    }
}

Partially refund a payment

Send a partial refund request to return a portion of the settled amount to your customer.

POST your request to the cardPayments:partialRefund action link, returned in your settlement or customerInitiatedTransactions response.

Partial refund request

Send the amount to refund and the authorization currency in the body.

POST https://try.access.worldpay.com/payments/settlements/refunds/partials/eyJrIjoiazNhYjYzMiJ9

{
    "value": {
        "amount": 125,
        "currency": "GBP"
    },
    "reference": "partial-refund-reference"
}

Partial refund response

In the response you get a 202 HTTP code which confirms we have received your request. The request has not processed at this stage. You must query the payment to check the status. You can find a link for this in the response body.

Best Practice

If you're using our events service, as per our best practice, you should already have the latest payment status.

{
    "_links": {
        "cardPayments:partialRefund": {
            "href": "https://try.access.worldpay.com/payments/settlements/refunds/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "cardPayments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [{
            "name": "cardPayments",
            "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}",
            "templated": true
        }]
    }
}

Online refunds

Online refunds allow you to provide notice to cardholders that a refund attempt has been either successfully authorized or refused by the issuer.
The response for online refunds is the same as for standard refunds: you get a 202 HTTP code which confirms we have received your request.

However, the event webhook will contain a refund.onlineRefundAuthorization code for a successful online refund, or a refund.refusal object for a refused online refund.



Reverse a payment

Your reversal request is processed as a cancel or refund request. This depends on the time passed after your customerInitiatedTransactions request was submitted. For US entities the payment is refunded one day after a successful request. Any other payment moves to refunded after 15 minutes.

POST to the cardPayments:reversal action link received in your customerInitiatedTransactions or merchantInitiatedTransactions response.

Reversal request

POST https://try.access.worldpay.com/payments/sales/reversals/eyJrIjoiazNhYjYzMiJ9

Note

No request body is needed for this request.

Reversal response

In the response you get a 202 HTTP code which confirms we have received your request. The request has not processed at this stage. You must query the payment to check if it was canceled or refunded. You can find a link for this in the response body.

Best Practice

If you're using our events service, as per our best practice, you should already have the latest payment status.

{
    "_links": {
        "cardPayments:events": {
            "href": "https://access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [
            {
                "name": "cardPayments",
                "href": "https://access.worldpay.com/rels/cardPayments/{rel}",
                "templated": true
            }
        ]
    }
}

Next steps


Query a payment