Last Updated: 29 August 2024 | Change Log

Payout to a wallet

Use our card on file resource to authorize a payment with a digital wallet.

Note

You must integrate with Google Pay or Apple Pay before you can submit a wallet payment request to our Payments API.

Payout to wallet flow

Integrate with your mobile wallet provider: Apple Pay and Google Pay
Integrate with our Payments API - use our payments:cardOnFileAuthorize endpoint with your encrypted payload - see below
You receive a tokens:token in your response
Integrate with our Payouts API - use your token to make a payout with payoutInstrument `"type": "card/tokenized"

Card on file authorization request

POST your initial card on file authorizations to our payments:cardOnFileAuthorize action link resource received in your query the payments root resource request.

Card on file authorization example request:

POST https://try.access.worldpay.com/payments/authorizations/cardOnFile

cardOnFile authorization request body

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/wallet+applepay",
            "walletToken": "{\"version\": \"EC_v1\",\"data\": \"kdHd..GQ==\",\"signature\": \"MIAGCSqGSIb3DQEH...AAA\",\"header\": {\"transactionId\": \"d3b28af..f8\",\"ephemeralPublicKey\": \"MFkwE..Q==\",\"publicKeyHash\": \"dxCK..6o=\"}}"
        }
    }
}

Descriptions of your authorization request parameters

Parameter	Required	Description
`transactionReference`	✅	A unique reference generated by you that is used to identify a payment throughout its lifecycle. See transaction reference format, for more details and the best practices.
`merchant`	✅	An object that contains information about the merchant.
`merchant.entity`	✅	Directs your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries. Contact your Implementation Manager for more details.
`instruction`	✅	An object that contains all the information related to the payment.
`instruction.narrative`	✅	The text that appears on your customer's statement. Used to identify the merchant. See narrative format for more details and best practices.
`narrative.line1`	✅	The first line of the narrative which appears on your customer's statement (24 characters max. If character is not supported it is replaced with a space.). See narrative `line1` format for more details.
`instruction.value`	✅	An object that contains information about the value of the payment.
`value.currency`	✅	The three digit currency code. See list of supported currencies.
`value.amount`	✅	The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our currency table.
`instruction.paymentInstrument`	✅	An object that contains the payment type and details. You must integrate with Apple Pay/ Google Pay first to use the `card/wallet+applepay`/`card/wallet+googlepay` `paymentInstrument`.

cardOnFile authorization optional fields

The requests below contain all the mandatory and optional fields needed for a successful cardOnFile authorization request. The full request schema is also available in our API reference.

Complete card on file authorization request schema

Full cardOnFile authorization request body:

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "intent": "instalment",
        "narrative": {
            "line1": "Mind Palace Ltd",
            "line2": "Memory265-13/08/1876"
        },
        "value": {
            "currency": "GBP",
            "amount": 1000
        },
        "paymentInstrument": {
            "type": "card/wallet+applepay",
            "walletToken": "{\"version\": \"EC_v1\",\"data\": \"kdHd..GQ==\",\"signature\": \"MIAGCSqGSIb3DQEH...AAA\",\"header\": {\"transactionId\": \"d3b28af..f8\",\"ephemeralPublicKey\": \"MFkwE..Q==\",\"publicKeyHash\": \"dxCK..6o=\"}}",
            "billingAddress": {
                "address1": "221B Baker Street",
                "address2": "Marylebone",
                "address3": "Westminster",
                "postalCode": "NW1 6XE",
                "city": "London",
                "state": "Greater London",
                "countryCode": "GB"
            }
        }
    }
}

Descriptions of your card on file authorization request parameters

Parameter	Required	Description
`instruction.intent`	❌	A parameter detailing the reason for this particular repeat agreement. Possible value: `instalment`
`narrative.line2`	❌	Additional details about the payment e.g. order number, telephone number.

Card on file response

Successful response

You receive:

an HTTP code 201
an "outcome": "authorized"
risk factors (only returned if issuer identifies conflict)
a scheme reference
a paymentInstrument detailing brand information about the card that was used
links to cancel, settle, partially settle or query a payment payment events
authorization links
a token link you can use to make a Payout

Refused response