The Payment lifecycle API from Worldpay — 6 operation(s) for payment lifecycle.
openapi: 3.0.1
info:
title: 3DS 3DS actions Payment lifecycle API
description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n ```\n Authorization: {your_credentials}\n ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n<br /> <br />\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n ```\n Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n ```\nWe use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our 3DS API.\n\nWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`.\n<br /><br />\n\n\n__DNS whitelisting__ \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
version: '3'
x-metadata:
category:
- 3DS
- SCA Exemptions
business:
- Enterprise
catalog-list: true
generated: false
servers:
- url: https://try.access.worldpay.com
description: Test (Try)
- url: https://access.worldpay.com
description: Live
security:
- BasicAuth: []
tags:
- name: Payment lifecycle
paths:
/apmPayments/{paymentId}:
get:
description: Lookup the state of a payment, including the available action that can be performed.
operationId: query
parameters:
- description: The identifier of the payment resource.
in: path
name: paymentId
required: true
schema:
type: string
- description: The API version.
in: header
name: WP-Api-Version
required: true
schema:
type: string
enum:
- '2024-07-01'
responses:
'200':
content:
application/json:
examples:
authorized:
$ref: '#/components/examples/query-202-authorized'
pending:
$ref: '#/components/examples/query-202-pending'
sentForRefund:
$ref: '#/components/examples/query-202-sentForRefund'
sentForSettlement:
$ref: '#/components/examples/query-202-sentForSettlement'
schema:
$ref: '#/components/schemas/ApmPaymentResourceQuery'
description: Request successful.
'400':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-400'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Bad request.
'401':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-401'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: Client is not authorized due to missing or invalid Authorization header.
'404':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-404'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Payment resource not found.
'500':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-500'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: A problem occurred processing the request on our side.
summary: Get the last event for an APM payment
tags:
- Payment lifecycle
/apmPayments/{paymentId}/confirmations:
post:
description: Create a confirm payment request for smart button functionality.
operationId: confirmPaymentV2
parameters:
- description: The identifier of the payment resource.
in: path
name: paymentId
required: true
schema:
type: string
- description: The API version.
in: header
name: WP-Api-Version
required: true
schema:
type: string
enum:
- '2024-07-01'
responses:
'201':
content:
application/json:
examples:
Full example:
$ref: '#/components/examples/confirm-payment-201'
schema:
$ref: '#/components/schemas/ApmPaymentResourceNoActions'
description: Request successful.
'400':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-400'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Bad request.
'401':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-401'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: Client is not authorized due to missing or invalid Authorization header.
'404':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-404'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Payment resource not found.
'500':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-500'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: A problem occurred processing the request on our side.
summary: Confirm payment
tags:
- Payment lifecycle
/apmPayments/{paymentId}/reversals:
post:
description: Perform a reversal on the funds taken from a sale.
operationId: reverse
parameters:
- description: The identifier of the payment resource.
in: path
name: paymentId
required: true
schema:
type: string
- description: The content type of the request body.
in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/json
- description: The API version.
in: header
name: WP-Api-Version
required: false
schema:
type: string
enum:
- '2024-07-01'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Reversal'
examples:
Reversal:
$ref: '#/components/examples/payment-reversal'
Pix reversal:
$ref: '#/components/examples/payment-reversal-pix'
Klarna reversal:
$ref: '#/components/examples/payment-reversal-klarna'
required: false
responses:
'202':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/reverse-202'
schema:
$ref: '#/components/schemas/ApmPaymentResourceNoActions'
description: OK
'400':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-400'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Bad request.
'401':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-401'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: Client is not authorized due to missing or invalid Authorization header.
'404':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-404'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Payment resource not found.
'500':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-500'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: A problem occurred processing the request on our side.
summary: Reverse an APM payment
tags:
- Payment lifecycle
/apmPayments/{paymentId}/partialReversals:
post:
description: Perform a partial reversal on the funds taken from a sale.
operationId: partialReverseV2
parameters:
- description: The identifier of the payment resource.
in: path
name: paymentId
required: true
schema:
type: string
- description: The content type of the request body.
in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/json
- description: The API version.
in: header
name: WP-Api-Version
required: true
schema:
type: string
enum:
- '2024-07-01'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PartialReversal'
examples:
Reversal:
$ref: '#/components/examples/payment-reversal'
Pix reversal:
$ref: '#/components/examples/payment-reversal-pix'
Klarna reversal:
$ref: '#/components/examples/payment-reversal-klarna'
required: true
responses:
'202':
content:
application/json:
examples:
Full example:
$ref: '#/components/examples/reverse-202'
schema:
$ref: '#/components/schemas/ApmPaymentResourceNoActions'
description: Request successful.
'400':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-400'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Bad request.
'401':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-401'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: Client is not authorized due to missing or invalid Authorization header.
'404':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-404'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Payment resource not found.
'500':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-500'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: A problem occurred processing the request on our side.
summary: Partial reverse an APM payment
tags:
- Payment lifecycle
/apmPayments/{paymentId}/settlements:
post:
operationId: settle
parameters:
- in: path
name: paymentId
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SettlementPayload'
examples:
Settlement:
$ref: '#/components/examples/payment-settlement'
Klarna settlement:
$ref: '#/components/examples/payment-settlement-klarna'
required: false
responses:
'202':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/settlement-202'
schema:
$ref: '#/components/schemas/ApmPaymentResourceNoActionsSettlement'
description: OK
'400':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-400'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Bad request.
'401':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-401'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: Client is not authorized due to missing or invalid Authorization header.
'404':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-404'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Payment resource not found.
'500':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-500'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: A problem occurred processing the request on our side.
summary: Settle an APM payment
tags:
- Payment lifecycle
/apmPayments/{paymentId}/partialSettlements:
post:
description: Perform a settlement on authorized funds. Not all APMs support this, please check the links returned from querying a payment.
operationId: settleV2
parameters:
- description: The identifier of the payment resource.
in: path
name: paymentId
required: true
schema:
type: string
- description: The content type of the request body.
in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/json
- description: The API version.
in: header
name: WP-Api-Version
required: true
schema:
type: string
enum:
- '2024-07-01'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PartialSettlement'
examples:
Settlement:
$ref: '#/components/examples/payment-settlement'
Klarna settlement:
$ref: '#/components/examples/payment-settlement-klarna'
required: true
responses:
'202':
content:
application/json:
examples:
Full example:
$ref: '#/components/examples/settlement-202'
schema:
$ref: '#/components/schemas/ApmPaymentResourceNoActionsSettlement'
description: Request successful.
'400':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-400'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Bad request.
'401':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-401'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: Client is not authorized due to missing or invalid Authorization header.
'404':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-404'
schema:
$ref: '#/components/schemas/AccessApiValidationErrorResponse'
description: Payment resource not found.
'500':
content:
application/json:
examples:
Example:
$ref: '#/components/examples/response-500'
schema:
$ref: '#/components/schemas/AccessApiErrorResponse'
description: A problem occurred processing the request on our side.
summary: Partial settle an APM payment
tags:
- Payment lifecycle
components:
schemas:
KlarnaNetworkOrderSettlement:
type: object
description: Object that contains the complete list of lines relating to the transaction.
properties:
items:
type: array
items:
$ref: '#/components/schemas/KlarnaNetworkOrderItemSettlement'
SelfLink:
type: object
description: The URL you can invoke to fetch the last event for the payment.
properties:
href:
type: string
SettlementPayload:
type: object
description: Settlement request
properties:
reference:
type: string
maxLength: 128
minLength: 1
pattern: ^[a-zA-Z0-9\\-]*$
value:
$ref: '#/components/schemas/Value'
shipping:
$ref: '#/components/schemas/ShippingSettlement'
order:
$ref: '#/components/schemas/KlarnaNetworkOrderSettlement'
required:
- value
Reversal:
type: object
description: Partial reversal request
properties:
reference:
type: string
maxLength: 128
minLength: 1
pattern: ^[a-zA-Z0-9\\-]*$
value:
$ref: '#/components/schemas/Value'
reasonCode:
type: string
description: Mandatory for Pix payment method, not relevant for other payment methods.
enum:
- BE08
- FR01
- MD06
- SL02
order:
$ref: '#/components/schemas/KlarnaNetworkOrderSettlement'
required:
- value
CourierSettlement:
type: object
properties:
trackingId:
type: string
description: If you are providing multiple entries, a 255 character total limit exists for the combined trackingId length.
maxLength: 100
minLength: 1
ApmPaymentResourceNoActionsSettlement:
type: object
description: A payment resource.
properties:
paymentId:
type: string
description: The identifier of the payment resource.
lastEvent:
type: string
enum:
- authorized
- cancelFailed
- cancelled
- cancelRequested
- sentForSettlement
- sentForAuthorization
- settlementFailed
- chargebackReversed
- chargedBack
- disputeExpired
- disputeFundsHeld
- disputeFundsReleased
- disputeReserveReleased
- error
- expired
- disputeInformationRequested
- disputInformationSupplied
- miscellaneous
- pending
- refunded
- refundExpired
- refundFailed
- refundReversed
- refused
- refusedByIssuer
- requestExpired
- sentForRefund
- settled
- settlementReversed
- cancelledByCustomer
- signedFormReceived
- unknown
- manuallyAmended
_links:
$ref: '#/components/schemas/Links'
_actions:
type: object
commandId:
type: string
Links:
type: object
description: Links to resources related to the request.
properties:
self:
$ref: '#/components/schemas/SelfLink'
Value:
type: object
description: The value of the payment.
properties:
amount:
type: integer
format: int64
description: The amount in the lowest denomination of the currency e.g. pennies for GBP, cents for USD.
example: 12
minimum: 1
maximum: 2147483647
currency:
type: string
description: The supported [ISO 4217 currency codes](/products/reference/supported-countries-currencies#iso-currency-codes).
enum:
- AED
- AFN
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BRL
- BSD
- BTN
- BWP
- BYN
- BZD
- CAD
- CDF
- CHF
- CLP
- CNH
- CNY
- COP
- CRC
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EGP
- ERN
- ETB
- EUR
- FJD
- FKP
- GBP
- GEL
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HTG
- HUF
- IDR
- ILS
- INR
- IQD
- IRR
- ISK
- JMD
- JOD
- JPY
- KES
- KHR
- KMF
- KPW
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LSL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRU
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RWF
- SAR
- SBD
- SCR
- SEK
- SGD
- SHP
- SLE
- SLL
- SOS
- SRD
- STN
- SVC
- SYP
- SZL
- THB
- TJS
- TMT
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- UYU
- UZS
- VES
- VND
- VUV
- WST
- XAF
- XCD
- XOF
- XPF
- YER
- ZAR
- ZMW
required:
- amount
- currency
AccessApiErrorResponse:
type: object
properties:
errorName:
type: string
message:
type: string
ActionsQuery:
type: object
properties:
reverse:
$ref: '#/components/schemas/ActionLinkV2'
partialReverse:
$ref: '#/components/schemas/ActionLinkV2'
settle:
$ref: '#/components/schemas/ActionLinkV2'
partialSettle:
$ref: '#/components/schemas/ActionLinkV2'
PartialReversal:
type: object
description: Partial reversal request
properties:
reference:
type: string
maxLength: 128
minLength: 1
pattern: ^[a-zA-Z0-9\\-]*$
value:
$ref: '#/components/schemas/Value'
reasonCode:
type: string
description: Mandatory for Pix payment method, not relevant for other payment methods.
enum:
- BE08
- FR01
- MD06
- SL02
order:
$ref: '#/components/schemas/KlarnaNetworkOrderSettlement'
required:
- value
AccessApiValidationErrorResponse:
type: object
properties:
errorName:
type: string
message:
type: string
validationErrors:
type: array
items:
$ref: '#/components/schemas/AccessApiValidationError'
ActionLinkV2:
type: object
description: Link to resources to reverse operation.
properties:
href:
type: string
method:
type: string
ShippingSettlement:
type: object
properties:
courier:
type: array
items:
$ref: '#/components/schemas/CourierSettlement'
ApmPaymentResourceNoActions:
type: object
description: A payment resource.
properties:
paymentId:
type: string
description: The identifier of the payment resource.
lastEvent:
type: string
enum:
- authorized
- cancelFailed
- cancelled
- cancelRequested
- sentForSettlement
- sentForAuthorization
- settlementFailed
- chargebackReversed
- chargedBack
- disputeExpired
- disputeFundsHeld
- disputeFundsReleased
- disputeReserveReleased
- error
- expired
- disputeInformationRequested
- disputInformationSupplied
- miscellaneous
- pending
- refunded
- refundExpired
- refundFailed
- refundReversed
- refused
- refusedByIssuer
- requestExpired
- sentForRefund
- settled
- settlementReversed
- cancelledByCustomer
- signedFormReceived
- unknown
- manuallyAmended
_links:
$ref: '#/components/schemas/Links'
_actions:
type: object
commandId:
type: string
ApmPaymentResourceQuery:
type: object
description: A payment resource.
properties:
paymentId:
type: string
description: The identifier of the payment resource.
lastEvent:
type: string
enum:
- authorized
- cancelFailed
- cancelled
- cancelRequested
- sentForSettlement
- sentForAuthorization
- settlementFailed
- chargebackReversed
- chargedBack
- disputeExpired
- disputeFundsHeld
- disputeFundsReleased
- disputeReserveReleased
- error
- expired
- disputeInformationRequested
- disputInformationSupplied
- miscellaneous
- pending
- refunded
- refundExpired
- refundFailed
- refundReversed
- refused
- refusedByIssuer
- requestExpired
- sentForRefund
- settled
- settlementReversed
- cancelledByCustomer
- signedFormReceived
- unknown
- manuallyAmended
_links:
$ref: '#/components/schemas/Links'
_actions:
$ref: '#/components/schemas/ActionsQuery'
AccessApiValidationError:
description: Validation error object.
KlarnaNetworkOrderItemSettlement:
type: object
description: Object that contains details for one line of the order. There can be multiple object items.
properties:
productCode:
type: string
description: Your customer facing product code, e.g. SKU (Stock Keeping Unit) or similar.
maxLength: 255
minLength: 1
pattern: ^([a-zA-Z0-9]*)$
name:
type: string
description: Description or name of item e.g., “Mobile Phone”.
maxLength: 1024
minLength: 1
pattern: ([a-zA-Z0-9 ]*)
quantity:
type: integer
description: Number of items being purchased.
minimum: 1
unitCost:
type: integer
maximum: 2147483648
minimum: -2147483648
description: Cost for each unit of the item with tax included.
totalTaxAmount:
type: integer
description: 'How much of totalAmount is tax. If you need to work it out backwards the formula is: totalTaxAmount = totalAmount - (totalAmount / (1+(taxRate/10000))).'
maximum: 2147483648
minimum: 0
totalAmount:
type: integer
description: 'Sum of all chargeable elements on the line added together. Formula is: totalAmount = (unitCost x quantity) - totalDiscountAmount.'
minimum: -2147483648
maximum: 2147483648
productUrl:
type: string
description: Link to the product page that can later be embedded in communications between Klarna and your customer.
maxLength: 2048
minLength: 1
imageUrl:
type: string
description: "Link to the product image that can later be embedded in communications between Klarna and your customer.\n\n Note: we recommend you submit this to improve the post-purchase customer experience."
maxLength: 2048
minLength: 1
PartialSettlement:
type: object
description: Partial settlement request
properties:
reference:
type: string
maxLength: 128
minLength: 1
pattern: ^[a-zA-Z0-9\\-]*$
value:
$ref: '#/components/schemas/Value'
shipping:
$ref: '#/components/schemas/ShippingSettlement'
order:
$ref: '#/components/schemas/KlarnaNetworkOrderSettlement'
required:
- value
examples:
payment-settlement:
value:
reference: string
value:
amount: 12
currency: AED
payment-settlement-klarna:
value:
reference: string
value:
amount: 12
currency: AED
shipping:
courier:
- trackingId: BBB0000000
order:
items:
- name: Panaphonics DH12-HK & Accessories
quantity: 1
unitCost: 12000
totalTaxAmount: 12000
totalAmount: 2000
productUrl: http://www.merchanturl.com/products/f2ytrdmn
imageUrl: http://www.merchanturl.com/products/f2ytrdmn_small.jpg
payment-reversal-klarna:
value:
reference: string
value:
amount: 12
currency: EUR
order:
items:
- productCode: fff1223
name: Red Hat
quantity: 1
unitCost: 1234
totalTaxAmount: 0
totalAmount: 1234
productUrl: https://example.com
imageUrl: https://example.com
- productCode: fff1226
name: Red Hat
quantity: 1
unitCost: 1234
totalTaxAmount: 0
totalAmount: 1234
productUrl: https://example.com
imageUrl: https://example.com
confirm-payment-201:
value:
paymentId: uK9Oh5zz4yKhGuFofhhnC_h2WwCXUTVwK1Lx7OP-WOiwgLd0DJ5uYK8NLsKG-rFtM4xXFxk15W-f-R1c3u_fq6rRIVQO_lZhwklop_5RcXz35RD_4TJfbjKQAyEFQXOTgUZHQIK3iu8VcHfOiFVHyN-y7ZDRr24t7o6s_bHlZxpba-zPVQ7PG1AztEwRCfVJ
lastEvent: authorized
_links:
self:
href: https://try.access.worldpay.com/apmPayments/uK9Oh5zz4yKhGuFofhhnC_h2WwCXUTVwK1Lx7OP-WOiwgLd0DJ5uYK8NLsKG-rFtM4xXFxk15W-f-R1c3u_fq6rRIVQO_lZhwklop_5RcXz35RD_4TJfbjKQAyEFQXOTgUZHQIK3iu8VcHfOiFVHyN-y7ZDRr24t7o6s_bHlZxpba-zPVQ7PG1AztEwRCfVJ
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/worldpay/refs/heads/main/openapi/worldpay-payment-lifecycle-api-openapi.yml