The Query a payment API from Worldpay — 2 operation(s) for query a payment.
openapi: 3.0.1
info:
title: 3DS 3DS actions Query a payment 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: Query a payment
paths:
/payments/events/{linkData}:
get:
tags:
- Query a payment
summary: Query payment status
description: "Send a request to find out the current status of your payment after it has been authorized using the events action link.\n\n **Note:** It can take up to 15 minutes for a payment event to update."
operationId: eventQuery
parameters:
- name: linkData
in: path
description: Action link that's received in your request.
required: true
schema:
type: string
- in: header
name: Content-Type
required: true
schema:
type: string
example: application/vnd.worldpay.payments-v7+json
- in: header
name: Accept
required: true
schema:
type: string
example: application/vnd.worldpay.payments-v7+json
responses:
'200':
description: Retrieve the last event of a payment
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/payments_events_200_response'
examples:
Querying a payment event with a transaction reference:
description: Querying a payment event with a transaction reference
value:
lastEvent: Authorized
_links:
cardPayments:cancel: /payments/authorizations/cancellations/:linkData
cardPayments:settle: /payments/settlements/full/:linkData
cardPayments:partialSettle: /payments/settlements/partials/:linkData
curies:
- name: payments
href: /rels/payments/{rel}
templated: true
'400':
description: Bad request
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
examples:
Bad request:
description: Bad request
value:
errorName: bodyDoesNotMatchSchema
message: The json body provided does not match the expected schema
validationErrors:
- errorName: fieldMustBeString
message: Element at path must be a string
jsonPath: $.value.currency
'401':
description: Unauthorized
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
description: Unauthorized
value:
errorName: accessDenied
message: Access to the requested resource has been denied
'404':
description: Not found
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
notFound:
description: Not found
value:
errorName: endpointNotFound
message: Requested endpoint was not found.
'415':
description: Unsupported media type
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unsupported:
description: Unsupported media type
value:
errorName: headerHasInvalidValue
message: Bad content type
'500':
description: Internal server error
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/payments/events:
get:
tags:
- Query a payment
summary: Query payment status recovery
description: "Send a request to find out the current status of your payment after it has been authorized using the events action link. \n\n **Important:** \n\n Only use this for recovery purposes, for example when your authorization request has timed out or you are unable to locate a payment through our [Payments Queries API](/products/payment-queries). If the query returns results, you can manage the payment using the next action links returned in the response of your GET request."
operationId: eventRecovery
parameters:
- in: header
name: Content-Type
required: true
schema:
type: string
example: application/vnd.worldpay.payments-v7+json
- in: header
name: Accept
required: true
schema:
type: string
example: application/vnd.worldpay.payments-v7+json
responses:
'200':
description: Retrieve the last event of a payment
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/payments_events_recovery_200_response'
examples:
Querying a payment event with a transaction reference:
description: Querying a payment event with a transaction reference
value:
lastEvent: Authorized
_links:
cardPayments:cancel: /payments/authorizations/cancellations/:linkData
cardPayments:settle: /payments/settlements/full/:linkData
cardPayments:partialSettle: /payments/settlements/partials/:linkData
curies:
- name: payments
href: /rels/payments/{rel}
templated: true
'400':
description: Bad request
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
examples:
Bad request:
description: Bad request
value:
errorName: bodyDoesNotMatchSchema
message: The json body provided does not match the expected schema
validationErrors:
- errorName: fieldMustBeString
message: Element at path must be a string
jsonPath: $.value.currency
'401':
description: Unauthorized
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
description: Unauthorized
value:
errorName: accessDenied
message: Access to the requested resource has been denied
'404':
description: Not found
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
notFound:
description: Not found
value:
errorName: endpointNotFound
message: Requested endpoint was not found.
'415':
description: Unsupported media type
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unsupported:
description: Unsupported media type
value:
errorName: headerHasInvalidValue
message: Bad content type
'500':
description: Internal server error
content:
application/vnd.worldpay.payments-v7+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ErrorResponse:
type: object
properties:
errorName:
type: string
message:
type: string
ValidationErrorResponse:
type: object
properties:
errorName:
type: string
message:
type: string
validationErrors:
type: array
description: Further error details
items:
type: object
properties:
errorName:
type: string
message:
type: string
jsonPath:
type: string
payments_events_200_response:
required:
- lastEvent
type: object
properties:
lastEvent:
type: string
enum:
- Authorized
- Refused
- Sent for Settlement
- Sent for Refund
- Sent for Cancellation
- Refund failed
- Settlement failed
- Settled
- Refunded
- Error
- Expired
x-enumDescriptions:
Authorized: The payment has been approved and the funds have been reserved in your customer's account.
Refused: Your payment request has been declined.
Sent for Settlement: A request has been made to move the reserved funds in your customer's account and transfer them to your Worldpay account.
Sent for Refund: A request has been made to send funds back to your customer's account.
Sent for Cancellation: A request has been made to cancel the payment without sending it for settlement.
Refund failed: A refund request couldn't be processed and the funds were returned to your account.
Settlement failed: A settlement request couldn't be processed. Funds have not been transferred to your Worldpay account.
Settled: We have received the funds and are preparing to transfer them to your bank account. This event is only available in certain use cases.
Refunded: The card issuer has received the refund request and they will return the funds to your customer's account. This event is only available in certain use cases.
Error: The payment wasn't completed. You may want to reattempt the payment.
Expired: The authorization validity period ended before a settlement or cancel request was made.
payments_events_recovery_200_response:
required:
- lastEvent
type: object
properties:
lastEvent:
type: string
enum:
- Authorized
- Refused
- Sent for Settlement
- Sent for Refund
- Send for Cancellation
- Refund failed
- Settlement failed
- Settled
- Refunded
- Error
- Expired
x-enumDescriptions:
Authorized: The payment has been approved and the funds have been reserved in your customer's account.
Refused: Your payment request has been declined.
Sent for Settlement: A request has been made to move the reserved funds in your customer's account and transfer them to your Worldpay account.
Sent for Refund: A request has been made to send funds back to your customer's account.
Sent for Cancelation: A request has been made to cancel the payment without sending it for settlement.
Refund failed: A refund request couldn't be processed and the funds were returned to your account.
Settlement failed: A settlement request couldn't be processed. Funds have not been transferred to your Worldpay account.
Settled: We have received the funds and are preparing to transfer them to your bank account. This event is only available in certain use cases.
Refunded: The card issuer has received the refund request and they will return the funds to your customer's account. This event is only available in certain use cases.
Error: The payment wasn't completed. You may want to reattempt the payment.
Expired: The authorization validity period ended before a settlement or cancel request was made.
securitySchemes:
BasicAuth:
type: http
scheme: basic