Menu

Manage payments

API v6
Last updated March 2023
Change log

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

Best Practice: To manage your payments we recommend using ourevents serviceto 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 thepayments:cancelaction 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 arefund.

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 mustquerythe payment to check the status. You can find a link for this in the response body.

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

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


Settle an authorization

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

POST to thepayments:settleaction 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.

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 mustquerythe payment to check the status. You can find a link for this in the response body, as well as links torefund and partially refund.

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

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


Partially settle an authorization

To receive a portion of the funds of a payment, send us a partial settle request.

POST to thepayments:partialSettleaction link, returned in yourauthorization 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.

Partially settle request

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

Copied!
{
    "value": {
        "amount": 125,
        "currency": "GBP"
    },
    "reference": "partial-settle-reference"
}

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 seetransaction reference format.

Partially 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 mustquerythe payment to check the status. You can find a link for this in the response body, as well as links torefund, partially refund,partially settleandcancelyour payment.

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

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


Fully refund a payment

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

POST to the payments:refund action link received in yourfullsettlement,partialsettlement orsaleresponse.

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 mustquerythe payment to check the status. You can find a link for this in the response body.

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

Copied!
{
    "_links": {
        "payments:events": {
            "href": "https://access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [
            {
                "name": "payments",
                "href": "https://access.worldpay.com/rels/payments/{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 payments:partialRefund action link, returned in yoursettlementorsaleresponse.

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

Copied!
{
    "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 mustquerythe payment to check the status. You can find a link for this in the response body.

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

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


Reverse a sale

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

POST to the payments:reversal action link received in yourmigrateCardOnFileSaleorrecurringSaleresponse.

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 mustquerythe 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 ourevents service, as per our best practice, you should already have the latest payment status.

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

Next steps

Query a payment