openapi: 3.2.0 info: title: Ppro Authorization Endpoints API version: v1 description: 'Operations tagged Authorization Endpoints across 4 of this provider''s published API definitions: ppro-payment-agreements-openapi.yml, ppro-payment-agreements.json, ppro-payment-charges-openapi.yml, ppro-payment-charges.json. Each path carries the servers of the definition it was published in.' servers: - url: https://api.sandbox.eu.ppro.com description: Production - Sandbox environment for integration testing - url: https://api.qa.eu.ppro.com/v1/payment-agreements description: QA - url: https://api.eu.ppro.com description: Production endpoint for EU customers security: - bearer_token: [] tags: - name: Authorization Endpoints paths: /v1/payment-agreements/{agreementId}/authorizations: post: tags: - Authorization Endpoints summary: Update authorization description: Provide additional data required to proceed with the authorization. operationId: confirm parameters: - name: agreementId in: path required: true schema: type: string - name: Merchant-Id in: header description: The merchant identifier. required: true schema: type: string example: merch_cb6RQnZbBwSBkn34QYXhr requestBody: content: application/json: schema: $ref: '#/components/schemas/ConfirmationRequest' required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/ConfirmationResponse' servers: - url: https://api.sandbox.eu.ppro.com description: Production - Sandbox environment for integration testing - url: https://api.qa.eu.ppro.com/v1/payment-agreements description: QA /v1/payment-charges: get: tags: - Authorization Endpoints summary: List payment charges description: 'Returns all payment charges that match the given search criteria. ' operationId: searchPaymentCharge parameters: - name: merchantPaymentChargeReference in: query required: false schema: type: string - name: agreementId in: query required: false schema: type: string - name: page in: query required: false schema: type: string - name: Merchant-Id in: header description: The merchant identifier. required: true schema: type: string example: merch_cb6RQnZbBwSBkn34QYXhr - name: Request-Reference in: header description: Unique request reference to facilitate debugging. schema: type: string example: abc-unique-value-for-tracing responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/GetPaymentChargesResponse' '409': description: Duplicate request received with the same idempotency key. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' '504': description: Call to the upstream dependency timed out. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' post: tags: - Authorization Endpoints summary: Create a payment charge description: Creates a payment charge. operationId: authorize parameters: - name: Merchant-Id in: header description: The merchant identifier. required: true schema: type: string example: merch_cb6RQnZbBwSBkn34QYXhr - name: Request-Reference in: header description: Unique request reference to facilitate debugging. schema: type: string example: abc-unique-value-for-tracing - name: Request-Idempotency-Key in: header description: Optional Idempotency Key for the request. Sending duplicate requests will result in 409 HTTP status code. schema: type: string example: xyz-unique-value-for-idempotency requestBody: content: application/json: schema: $ref: '#/components/schemas/AuthorizationRequest' required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/PaymentChargeResponse' '409': description: Duplicate request received with the same idempotency key. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' '504': description: Call to the upstream dependency timed out. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' servers: - url: https://api.sandbox.eu.ppro.com description: Production - Sandbox environment for integration testing - url: https://api.eu.ppro.com description: Production endpoint for EU customers /v1/payment-charges/{paymentChargeId}/authorizations: get: tags: - Authorization Endpoints summary: List authorizations description: Returns all authorizations associated with the payment charge. operationId: getAuthorizations parameters: - name: paymentChargeId in: path required: true schema: type: string - name: Merchant-Id in: header description: The merchant identifier. required: true schema: type: string example: merch_cb6RQnZbBwSBkn34QYXhr - name: Request-Reference in: header description: Unique request reference to facilitate debugging. schema: type: string example: abc-unique-value-for-tracing responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/GetAuthorizationsResponse' '409': description: Duplicate request received with the same idempotency key. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' '504': description: Call to the upstream dependency timed out. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' post: tags: - Authorization Endpoints summary: Update authorization description: Provide additional data required to proceed with the authorization. operationId: confirm parameters: - name: paymentChargeId in: path required: true schema: type: string - name: Merchant-Id in: header description: The merchant identifier. required: false schema: type: string example: merch_cb6RQnZbBwSBkn34QYXhr - name: Request-Reference in: header description: Unique request reference to facilitate debugging. schema: type: string example: abc-unique-value-for-tracing - name: Request-Idempotency-Key in: header description: Optional Idempotency Key for the request. Sending duplicate requests will result in 409 HTTP status code. schema: type: string example: xyz-unique-value-for-idempotency requestBody: content: application/json: schema: $ref: '#/components/schemas/ConfirmationRequest_2' required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/PaymentChargeAuthorizationResponse' '409': description: Duplicate request received with the same idempotency key. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' '504': description: Call to the upstream dependency timed out. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' servers: - url: https://api.sandbox.eu.ppro.com description: Production - Sandbox environment for integration testing - url: https://api.eu.ppro.com description: Production endpoint for EU customers /v1/payment-charges/{paymentChargeId}: get: tags: - Authorization Endpoints summary: Get Payment Charge description: Returns the payment charge, given the charge ID. operationId: getPaymentCharge parameters: - name: paymentChargeId in: path required: true schema: type: string - name: Merchant-Id in: header description: The merchant identifier. required: true schema: type: string example: merch_cb6RQnZbBwSBkn34QYXhr - name: Request-Reference in: header description: Unique request reference to facilitate debugging. schema: type: string example: abc-unique-value-for-tracing responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/PaymentChargeResponse' '409': description: Duplicate request received with the same idempotency key. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' '504': description: Call to the upstream dependency timed out. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' servers: - url: https://api.sandbox.eu.ppro.com description: Production - Sandbox environment for integration testing - url: https://api.eu.ppro.com description: Production endpoint for EU customers /v1/payment-charges/{paymentChargeId}/authorizations/{authorizationId}: get: tags: - Authorization Endpoints summary: Get authorization description: Returns a specific authorization operation associated with the payment charge operationId: getAuthorization parameters: - name: paymentChargeId in: path required: true schema: type: string - name: authorizationId in: path required: true schema: type: string - name: Merchant-Id in: header description: The merchant identifier. required: true schema: type: string example: merch_cb6RQnZbBwSBkn34QYXhr - name: Request-Reference in: header description: Unique request reference to facilitate debugging. schema: type: string example: abc-unique-value-for-tracing responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/PaymentChargeAuthorizationResponse' '409': description: Duplicate request received with the same idempotency key. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' '504': description: Call to the upstream dependency timed out. content: application/json: schema: $ref: '#/components/schemas/ExceptionResponseBody' servers: - url: https://api.sandbox.eu.ppro.com description: Production - Sandbox environment for integration testing - url: https://api.eu.ppro.com description: Production endpoint for EU customers components: schemas: AdditionalData: type: object properties: merchantAdviceCode: type: string description: Merchant Advice Code (MAC) returned by the payment network on decline, indicating whether and when the payment may be retried. merchantAdviceCodeText: type: string description: Human-readable explanation of the Merchant Advice Code (MAC). AuthenticationResult: type: object properties: type: type: string description: The type of authentication result enum: - APP_NOTIFICATION - MULTI_FACTOR details: type: object additionalProperties: {} description: A map containing the authentication result details which format is understood by the payment processor of the associated payment method required: - details ConfirmationResponse: type: object properties: id: type: string description: The notification identifier. agreementStatus: type: string description: Resulting payment-agreement status after processing the notification. enum: - INITIALIZING - AUTHENTICATION_PENDING - AUTHORIZATION_PROCESSING - ACTIVE - REVOKED_BY_CONSUMER - REVOKED_BY_MERCHANT - REVOKED_BY_PROVIDER - FAILED failure: $ref: '#/components/schemas/ProcessingFailure' description: The processing failure if the notification operation failed. createdAt: type: string format: date-time description: The notification timestamp in ISO 8601 format. example: '2023-03-26T20:24:27.123Z' ProcessingFailure: type: object properties: failureType: type: string description: The failure type. enum: - INTERNAL_ERROR - INTERNAL_DECLINE - PROVIDER_ERROR - PROVIDER_DECLINE failureCode: type: string description: The failure code. providerFailureCode: type: string description: The payment provider failure code. failureMessage: type: string description: The failure message. isRetryable: type: boolean description: Indicates whether the merchant should create a fresh new attempt, where initiating a fresh new attempt at a later time may potentially result in a successful outcome. additionalData: $ref: '#/components/schemas/AdditionalData' ConfirmationRequest: type: object properties: authenticationResult: $ref: '#/components/schemas/AuthenticationResult' description: 'The outcome of processing the payment authentication challenge (eg: a payment provider generated token or a 3DS challenge response).' example: type: APP_NOTIFICATION details: instrumentProviderIdentity: '+34700000000' AuthenticationMethod: discriminator: propertyName: type mapping: APP_INTENT: '#/components/schemas/AppIntentAuthenticationMethod' 3DS: '#/components/schemas/ThreeDsAuthenticationMethod' SCAN_CODE: '#/components/schemas/ScanCodeAuthenticationMethod' MULTI_FACTOR: '#/components/schemas/MultiFactorAuthenticationMethod' APP_NOTIFICATION: '#/components/schemas/AppNotificationAuthenticationMethod' REDIRECT: '#/components/schemas/RedirectAuthenticationMethod' properties: type: type: string required: - type RedirectAuthenticationSettingsDetails: type: object properties: returnUrl: type: string description: The URL to which the consumer is redirected after completing an action, such as a payment or authentication flow. example: https://www.webshop.com/order-results-page RawCardInstrument: allOf: - $ref: '#/components/schemas/PaymentInstrument' - properties: details: description: The card details properties: brand: description: The card brand.
The value must be provided in uppercase. example: VISA number: description: The primary account number (PAN) of the card used for the payment. example: '4444333322221111' cvv: description: Card Verification Value used to authenticate the card during a payment. example: '123' holderName: description: The full name of the cardholder as it appears on the card. example: John Smith expiryMonth: format: int32 description: The two-digit expiration month of the card. example: '1' maximum: 12 minimum: 1 expiryYear: format: int32 description: The four-digit expiration year of the card. example: '2031' minimum: 2000 required: - expiryMonth - expiryYear - holderName - number validate: description: If included, PPRO will try to validate the instrument with a nominal-amount authorization. If validation fails, the instrument creation request will fail properties: currency: description: ISO 4217 3-letter currency code. example: EUR maxLength: 3 minLength: 3 taxIdentification: description: The consumer's tax identification number, like CUIT in Argentina, CPF in Brazil, RUT in Chile, NIF in Spain or Portugal, Numéro fiscal in France, and Codice Fiscale in Italy, or the equivalent tax identifier applicable in the consumer's country. example: '798154336790' required: - currency type: description: The `RAW_CARD` payment instrument type. enum: - RAW_CARD required: - details title: Payment Instrument (RAW_CARD) Links: type: object additionalProperties: $ref: '#/components/schemas/Link' ExternalThreeDs: type: object properties: authenticationStatus: type: string description: The 3DS authentication status code. enum: - SUCCESS - ATTEMPT_ACKNOWLEDGED - FAILED - AUTHENTICATION_UNAVAILABLE authenticationStatusReason: type: string description: The 3DS authentication status reason. enum: - CARD_AUTHENTICATION_FAILED - UNKNOWN_DEVICE - UNSUPPORTED_DEVICE - EXCEEDS_AUTHENTICATION_FREQUENCY_LIMIT - EXPIRED_CARD - INVALID_CARD_NUMBER - INVALID_TRANSACTION - NO_CARD_RECORD - SECURITY_FAILURE - STOLEN_CARD - SUSPECTED_FRAUD - TRANSACTION_NOT_PERMITTED_TO_CARDHOLDER - CARDHOLDER_NOT_ENROLLED_IN_SERVICE - TRANSACTION_TIMED_OUT_AT_THE_ACS - LOW_CONFIDENCE - MEDIUM_CONFIDENCE - HIGH_CONFIDENCE - VERY_HIGH_CONFIDENCE - EXCEEDS_ACS_MAXIMUM_CHALLENGES - NON_PAYMENT_TRANSACTION_NOT_SUPPORTED - THREE_RI_TRANSACTION_NOT_SUPPORTED authenticationValue: type: string description: The 3DS authentication CAVV. authenticationAlgorithm: type: string description: The 3DS authentication CAVV algorithm used. authenticationMode: type: string description: The 3DS authentication mode. enum: - SCA - FRICTIONLESS eci: type: string description: The 3DS authentication ECI. version: type: string description: The 3DS authentication version. externalId: type: string description: The 3DS authentication transaction identifier. externalAcsId: type: string description: The 3DS universally unique transaction identifier assigned by the ACS to identify a single transaction. Canonical format as defined in IETF RFC 4122. example: 4dc406b0-038d-43ef-a96c-c85352c5e2c0 score: type: string description: The 3DS score. challenge: $ref: '#/components/schemas/Challenge' description: The 3DS authentication challenge details. outOfScope: $ref: '#/components/schemas/OutOfScope' description: The 3DS out of scope object, to be used if the payment is out of scope of SCA RedirectAuthenticationDetails: type: object properties: requestUrl: type: string description: The URL where the consumer should be redirected in order to authenticate the payment. example: https://pay.playground.klarna.com/eu/hpp/payments/123abc requestMethod: type: string description: The redirect HTTP method. enum: - GET - POST AuthenticationResult_2: type: object properties: type: type: string description: The type of authentication result details: type: object additionalProperties: {} description: A map containing the authentication result details which format is understood by the payment processor of the associated payment method required: - details AirlineIndustryData: allOf: - $ref: '#/components/schemas/IndustryData' - type: object properties: details: $ref: '#/components/schemas/AirlineDetails' description: The airline industry specific details. type: type: string description: The `AIRLINE` industry data type. enum: - AIRLINE required: - details MultiFactorAuthenticationSettingsDetails: type: object properties: verificationCode: type: string description: Code generated to authenticate the user. example: '777123' Challenge: type: object properties: preference: type: string description: The 3DS authentication challenge initialization preference. enum: - NO_PREFERENCE - NO_CHALLENGE_REQUESTED - CHALLENGE_REQUESTED - CHALLENGE_MANDATED - DATA_ONLY outcome: type: string description: The 3DS authentication challenge outcome. enum: - CHALLENGE - FRICTIONLESS - DATA_ONLY exemptionReason: type: string description: The 3DS authentication challenge exemption reason. enum: - LOW_VALUE - LOW_RISK - TRUSTED_BENEFICIARY - FIXED_RECURRING cancellationReason: type: string description: The 3DS challenge cancellation indicator.Mandatory for CB transactions. enum: - CARDHOLDER_CANCELLED - REQUESTOR_CANCELLED - TRANSACTION_ABANDONED - TRANSACTION_TIMEOUT_ACS_OTHER - TRANSACTION_TIMEOUT_ACS_CREQ_NOT_RECEIVED - TRANSACTION_ERROR - UNKNOWN TravelDetails: type: object properties: travelType: type: string description: The travel type enum: - UNKNOWN - ONE_WAY - TWO_WAY - MULTIPLE example: MULTIPLE departureDate: type: string format: date description: Departure date example: '2025-06-10' returnDate: type: string format: date description: Return date example: '2025-06-15' departureLocation: type: string description: Departure location, if flight then provide IATA Airport Code example: Berlin arrivalLocation: type: string description: Arrival location, if flight then provide IATA Airport Code example: Madrid destinationCountry: type: string description: Destination country example: ES travelCompany: type: string description: Travel company name example: My Travel Company GmbH travelerCount: type: integer format: int64 description: Total number of travelers example: 4 buyerAmongTravelers: type: boolean description: Is the buyer consumer among travelers? example: true travelClass: type: string description: The class of travel example: PREMIUM travelInsured: type: boolean description: Whether the travel is insured? example: true travelDiscountVoucher: type: string description: Travel discount voucher example: TWENTY-OFF luggageSupplement: type: boolean description: Whether availing luggage supplement? example: true travelCanBeModifiedOrCanceled: type: boolean description: Can the travel be modified or canceled? example: true stayCompany: type: string description: Stay company name example: Hotel XYZ stayDestination: type: string description: Stay destination example: Madrid stayNightsCount: type: integer format: int64 description: Stay nights count example: 4 stayRoomRange: type: string description: Stay room category example: 4_STARS BancontactAccountDetails: type: object properties: bin: type: string description: The bank identification number example: '1234' maxLength: 8 minLength: 6 pattern: ^(\d{6}|\d{8})$ last4Digits: type: string description: The last 4 digits of the card example: '1234' maxLength: 4 minLength: 4 pattern: ^\d+$ expiryMonth: type: integer format: int32 description: The card expiration month example: 1 maximum: 12 minimum: 1 expiryYear: type: integer format: int32 description: The card expiration year example: 2024 minimum: 2000 panAlias: type: string description: The card PAN alias minLength: 1 required: - bin - expiryMonth - expiryYear - last4Digits - panAlias AirlineDetails: type: object properties: pnr: type: string description: The Passenger Name Record (PNR) associated with the airline booking. example: ABC123 numberOfPassengers: type: integer format: int32 description: The number of passengers on the booking. example: 2 minimum: 1 airlineCode: type: string description: The standardized two-letter or three-letter airline code assigned by IATA (International Air Transport Association) or ICAO (International Civil Aviation Organization). example: BA passengerEmail: type: string format: email description: The email address of the passenger. example: johnsmith@example.com passengerPhone: type: string description: The passenger phone number example: '+491521111111' passengerName: type: string description: The passenger name example: John Doe carrierCode: type: string description: The standardized two-letter or three-letter carrier code assigned by IATA (International Air Transport Association) or ICAO (International Civil Aviation Organization). example: AA tripSegments: type: array description: The trip segment details. items: $ref: '#/components/schemas/AirlineTripSegment' GatewayProcessingFailureResponse: type: object properties: failureType: type: string description: The failure type. enum: - INTERNAL_ERROR - INTERNAL_DECLINE - PROVIDER_ERROR - PROVIDER_DECLINE failureCode: type: string description: The failure code. providerFailureCode: type: string description: The payment provider failure code. failureMessage: type: string description: The failure message. isRetryable: type: boolean description: Indicates whether the merchant should create a fresh new attempt, where initiating a fresh new attempt at a later time may potentially result in a successful outcome. additionalData: $ref: '#/components/schemas/AdditionalData' PaymentChargeDiscardResponse: type: object properties: id: type: string description: The discard identifier. example: 5c019979-0751-469e-96e0-b67f1d95c577 status: type: string description: The discard status. enum: - DISCARDED - FAILED merchantDiscardReference: type: string description: The merchant provided discard reference. example: 5c019979-0751-469e-96e0-b67f1d95c577 type: type: string description: The type of the discard. enum: - AUTHENTICATION_TIMEOUT - PROVIDER_CONFIRMATION_TIMEOUT - MERCHANT_INITIATED_DISCARD example: MERCHANT_INITIATED_DISCARD failure: $ref: '#/components/schemas/GatewayProcessingFailureResponse' description: The discard processing failure if the discard operation failed. createdAt: type: string format: date-time description: The discard creation timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' updatedAt: type: string format: date-time description: The discard update timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' _links: $ref: '#/components/schemas/Links' readOnly: true AppIntentAuthenticationMethod: allOf: - $ref: '#/components/schemas/AuthenticationMethod' - type: object properties: details: $ref: '#/components/schemas/AppIntentAuthenticationDetails' description: The APP_INTENT authentication details. type: type: string description: The APP_INTENT authentication type. enum: - APP_INTENT title: Authentication Method (APP_INTENT) RedirectAuthenticationSettings: allOf: - $ref: '#/components/schemas/AuthenticationSettings' - type: object properties: settings: $ref: '#/components/schemas/RedirectAuthenticationSettingsDetails' description: The REDIRECT authentication settings. type: type: string description: The `REDIRECT` authentication type. enum: - REDIRECT AuthenticationSettings: discriminator: propertyName: type properties: type: type: string required: - type ScanCodeAuthenticationSettings: allOf: - $ref: '#/components/schemas/AuthenticationSettings' - type: object properties: settings: $ref: '#/components/schemas/ScanCodeAuthenticationSettingsDetails' description: The SCAN_CODE authentication details. type: type: string description: The `SCAN_CODE` authentication type. enum: - SCAN_CODE AppIntentAuthenticationSettingsDetails: type: object properties: mobileIntentUri: type: string description: A mobile deep link or intent URI to which the consumer is redirected after completing an action, such as a payment or authentication flow. example: webapp://checkout?paymentId=abc123 AppNotificationAuthenticationSettings: allOf: - $ref: '#/components/schemas/AuthenticationSettings' - type: object properties: settings: $ref: '#/components/schemas/AppNotificationAuthenticationSettingsDetails' description: The APP_NOTIFICATION authentication details. type: type: string description: The `APP_NOTIFICATION` authentication type. enum: - APP_NOTIFICATION RawCardInstrumentUpdate: allOf: - $ref: '#/components/schemas/PaymentInstrumentUpdate' - properties: details: description: The card update details properties: cvv: description: Card Verification Value used to authenticate the card during a payment. example: '123' required: - cvv type: description: The `RAW_CARD` payment instrument type. enum: - RAW_CARD required: - details title: Payment Instrument Update (RAW_CARD) ScanCodeAuthenticationDetails: type: object properties: codeType: type: string description: The type of the scan or of the code payload. enum: - QR - UPC - ITF - CODE128 - PAYMENT_REFERENCE codeImage: type: string description: The pre-generated scan code image for the ease of integration. example: https://authman-mobileapp.ppro.com/qr.png?payload=dXBpR2xvYmFsOi8vc3RhcnRfdHJhbnNhY3Rpb24/dHI9MTIzJmZyb21fcXI9dHJ1ZQ== codePayload: type: string description: The payload for the scan code or for the reference to construct the image or the UX on the partners side. example: upiGlobal://pay?tr=123&from_desktop=true codeDocument: type: string description: The URL of the pdf/html pay slip document. example: https://urltodocument.com codeProviderEntityId: type: string description: The identifier of the code provider entity. example: '45648' scanBy: type: string format: date-time description: The custom expiry timestamp (ISO 8601 format) before which the consumer is expected to complete the payment. example: '2022-11-03T11:23:47.123Z' RedirectAuthenticationMethod: allOf: - $ref: '#/components/schemas/AuthenticationMethod' - type: object properties: details: $ref: '#/components/schemas/RedirectAuthenticationDetails' description: The REDIRECT authentication details. type: type: string description: The REDIRECT authentication type. enum: - REDIRECT title: Authentication Method (REDIRECT) AppNotificationAuthenticationDetails: {} AuthorizationRequest: type: object properties: paymentMethod: type: string description: The payment method to be used for processing the payment charge.
The value must be provided in uppercase. example: WERO minLength: 1 pattern: ^[A-Z0-9_]+$ paymentMedium: type: string default: ECOMMERCE description: The medium through which the payment was initiated. enum: - ECOMMERCE - MOTO - POS example: ECOMMERCE paymentDescriptor: type: string description: A short descriptor for the payment that may appear on consumer statements.
This helps identify the transaction source or purpose. example: Webshop - ORDER 1234 initialSchemeAuthorizationReference: type: string description: The initial scheme authorization reference. It establishes the link back to the original agreement and authorization for recurring payments. example: MC1234567890ABCDE initialTransactionLinkReference: type: string description: 'Transaction Link Reference or Id (ex: Mastercard TLID) is a unique identifier for a transaction, used by some card networks for transaction chain linking, this is in addition to Network Transaction Identifiers. Provide the initial TLID when creating the subsequent Merchant-Initiated-Transactions.' example: atf3_8msFoZ6klReRDlQwn initiator: type: string description: The initiator of the payment charge. enum: - CONSUMER - MERCHANT scheduleType: type: string default: UNSCHEDULED description: Indicates the type of payment charge being processed. Use UNSCHEDULED for a one-off charge not tied to a schedule. Use SCHEDULED for charge that is part of a recurring schedule. Use SCHEDULED_RETRY for a retry attempt of a previously failed scheduled payment. The RECURRING enum is planned for deprecation and should not be used in new implementations. enum: - SCHEDULED - SCHEDULED_RETRY - UNSCHEDULED - RECURRING instrumentId: type: string description: The identifier of an existing payment instrument.
Instruments are used for recurring payments. example: instr_SNaRMvhYNFpXhEhgTVSed instrument: description: Provides additional details required by certain payment methods to process the payment successfully. oneOf: - $ref: '#/components/schemas/BancontactAccountInstrument' - $ref: '#/components/schemas/BankAccountInstrument' - $ref: '#/components/schemas/CardNetworkTokenInstrument' - $ref: '#/components/schemas/MockInstrument' - $ref: '#/components/schemas/PassthroughWalletInstrument' - $ref: '#/components/schemas/RawCardInstrument' instrumentUpdateDetails: description: Additional details to update an existing instrument. Must be used together with instrumentId. oneOf: - $ref: '#/components/schemas/RawCardInstrumentUpdate' amount: $ref: '#/components/schemas/Money' description: The amount to be authorized. consumer: $ref: '#/components/schemas/Consumer' description: Defines the details of the consumer. order: $ref: '#/components/schemas/Order' description: Defines order information, including purchased items and associated shipping details. merchantPaymentChargeReference: type: string description: A merchant-defined identifier that uniquely represents a single payment attempt. example: merch_payment_ref_123 authenticationSettings: type: array description: The authorization authentication settings. items: discriminator: propertyName: type mapping: REDIRECT: '#/components/schemas/RedirectAuthenticationSettings' EXTERNAL_3DS: '#/components/schemas/ExternalThreeDsAuthenticationSettings' 3DS: '#/components/schemas/ThreeDsAuthenticationSettings' SCAN_CODE: '#/components/schemas/ScanCodeAuthenticationSettings' MULTI_FACTOR: '#/components/schemas/MultiFactorAuthenticationSettings' APP_INTENT: '#/components/schemas/AppIntentAuthenticationSettings' APP_NOTIFICATION: '#/components/schemas/AppNotificationAuthenticationSettings' oneOf: - allOf: - $ref: '#/components/schemas/RedirectAuthenticationSettings' title: Authentication Settings - allOf: - $ref: '#/components/schemas/ExternalThreeDsAuthenticationSettings' title: Authentication Settings - allOf: - $ref: '#/components/schemas/ThreeDsAuthenticationSettings' title: Authentication Settings - allOf: - $ref: '#/components/schemas/ScanCodeAuthenticationSettings' title: Authentication Settings - allOf: - $ref: '#/components/schemas/MultiFactorAuthenticationSettings' title: Authentication Settings - allOf: - $ref: '#/components/schemas/AppIntentAuthenticationSettings' title: Authentication Settings - allOf: - $ref: '#/components/schemas/AppNotificationAuthenticationSettings' title: Authentication Settings autoCapture: type: boolean description: Indicates whether the payment charge should be automatically captured after a successful authorization. example: false webhooksUrl: type: string description: The URL to which the payment charge state changes will be notified. example: https://webshop.com/webhooks/payment-status pattern: ^(https)://[-a-zA-Z0-9+&@#/%?=~_|!:,.;]*[-a-zA-Z0-9+&@#/%=~_|] labels: type: object additionalProperties: type: string example: GTM_Campaign maxLength: 200 description: Custom labels associated with the payment charge. maxProperties: 50 propertyNames: type: string example: consumer_origin maxLength: 50 title: Add Labels required: - amount - consumer - paymentMethod ExternalThreeDsAuthenticationSettings: allOf: - $ref: '#/components/schemas/AuthenticationSettings' - type: object properties: settings: $ref: '#/components/schemas/ExternalThreeDs' description: The EXTERNAL_3DS authentication settings. type: type: string description: The `EXTERNAL_3DS` authentication type. enum: - EXTERNAL_3DS Client: type: object properties: ip: type: string description: The IP address of the client initiating the payment request.
Must be a valid IPv4 or IPv6 address. example: 11.22.22.33 userAgent: type: string description: The User-Agent string from the client’s HTTP request header. example: Mozilla/5.0 (X11; CrOS x86_64 8172.45.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.64 Safari/537.36 maxLength: 500 minLength: 0 MultiFactorAuthenticationSettings: allOf: - $ref: '#/components/schemas/AuthenticationSettings' - type: object properties: settings: $ref: '#/components/schemas/MultiFactorAuthenticationSettingsDetails' description: The MULTI_FACTOR authentication details. type: type: string description: The `MULTI_FACTOR` authentication type. enum: - MULTI_FACTOR MultiFactorAuthenticationDetails: {} Consumer: type: object properties: name: type: string description: The full name of the consumer making the payment. example: John Smith email: type: string format: email description: The email address of the consumer making the payment. example: johnsmith@example.com phone: type: string description: The phone number of the consumer making the payment. example: '+491521111111' birthDate: type: string format: date description: The date of birth of the consumer making the payment. example: '1995-06-06' country: type: string description: The country of residence of the consumer, represented as a two-letter ISO 3166-1 alpha-2 country code. example: DE pattern: ^[A-Z]{2}$ locale: type: string description: The locale of the consumer in the format of a language and country code. example: de-DE maxLength: 5 minLength: 5 pattern: ^[a-z]{2,3}-[A-Z]{2}$ client: $ref: '#/components/schemas/Client' description: Consumer's client data taxIdentification: type: string description: The consumer's tax identification number, like CUIT in Argentina, CPF in Brazil, RUT in Chile, NIF in Spain or Portugal, Numéro fiscal in France, and Codice Fiscale in Italy, or the equivalent tax identifier applicable in the consumer's country. example: '12345678909' merchantConsumerReference: type: string description: The merchant provided consumer reference. example: consumerRef-123 billingAddress: $ref: '#/components/schemas/Address' description: Defines the billing address of the consumer. profile: $ref: '#/components/schemas/Profile' description: Defines the consumers order history. required: - country EducationDetails: type: object properties: admissionNoticeUrl: type: string description: The admission notice url courseStartDate: type: string format: date description: Course start date example: '2025-06-10' courseEndDate: type: string format: date description: Course end date example: '2025-10-10' financedCourse: type: boolean description: Whether the course is financed? example: true diplomaCourse: type: boolean description: Whether the course is diploma? example: true postHighSchoolCourse: type: boolean description: Whether the course is post high school? example: true AirlineTripSegment: type: object properties: fareBasisCode: type: string description: The fare basis code is an alphanumeric identifier used by airlines to specify the fare rules, booking class, and restrictions associated with a ticket. example: M3L7X departureAirportCode: type: string description: The three-letter IATA airport code representing the departure airport for the flight. example: LHR destinationAirportCode: type: string description: The three-letter IATA airport code representing the destination airport for the flight. example: JFK flightNumber: type: string description: The flight number. example: BA117 departureDate: type: string format: date description: The departure date of the flight. example: '2025-01-01' flightCarrierCode: type: string description: The two-letter IATA airline code representing the carrier operating the flight. example: BA segmentId: type: string description: A unique identifier for a specific flight segment within a booking or itinerary. example: FLG4567 ExceptionResponseBody: type: object properties: status: type: integer format: int32 failureMessage: type: string timestamp: type: string format: date-time extensions: type: object additionalProperties: {} ScanCodeAuthenticationMethod: allOf: - $ref: '#/components/schemas/AuthenticationMethod' - type: object properties: details: $ref: '#/components/schemas/ScanCodeAuthenticationDetails' description: The SCAN_CODE authentication details. type: type: string description: The SCAN_CODE authentication type. enum: - SCAN_CODE title: Authentication Method (SCAN_CODE) AppIntentAuthenticationSettings: allOf: - $ref: '#/components/schemas/AuthenticationSettings' - type: object properties: settings: $ref: '#/components/schemas/AppIntentAuthenticationSettingsDetails' description: The `APP_INTENT` authentication type. type: type: string description: The APP_INTENT authentication type. enum: - APP_INTENT ThreeDsAuthenticationMethod: allOf: - $ref: '#/components/schemas/AuthenticationMethod' - type: object properties: details: $ref: '#/components/schemas/ThreeDsAuthenticationDetails' description: The 3DS authentication details. type: type: string description: The `3DS` authentication type. enum: - 3DS title: Authentication Method (3DS) ThreeDsAuthenticationSettingsDetails: type: object properties: returnUrl: type: string description: The URL to which the consumer is redirected after completing the 3D Secure authentication flow. example: https://www.ppro.com/ preference: type: string description: The preferred 3D Secure authentication flow. enum: - CHALLENGE - FRICTIONLESS ThreeDsAuthenticationSettings: allOf: - $ref: '#/components/schemas/AuthenticationSettings' - type: object properties: settings: $ref: '#/components/schemas/ThreeDsAuthenticationSettingsDetails' description: The 3DS authentication settings. type: type: string description: The `3DS` authentication type. enum: - 3DS Profile: type: object properties: createdDate: type: string format: date description: The date when the consumer profile was created. example: '2025-01-01' firstOrderDate: type: string format: date description: The consumer’s first order date. example: '2025-01-05' lastOrderDate: type: string format: date description: The consumer’s last order date. example: '2025-06-06' lifetimeOrderCount: type: integer format: int64 description: The consumer’s total number of orders. example: 10 lifetimeOrderValue: type: integer format: int64 description: The consumer’s total value of orders, expressed in the smallest currency unit. example: 1000 lifetimeCanceledOrderCount: type: integer format: int64 description: The consumer’s total number of cancelled orders. example: 1 GetPaymentChargesResponse: type: object properties: data: type: array description: The payment charges. items: $ref: '#/components/schemas/PaymentChargeResponse' nextPage: type: string _links: $ref: '#/components/schemas/Links' readOnly: true ScanCodeAuthenticationSettingsDetails: type: object properties: scanBy: type: string format: date-time description: The date and time at which the associated code expires. Must be provided in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' Address: type: object properties: firstName: type: string description: The first name of the individual associated with the address. example: John lastName: type: string description: The last name of the individual associated with the address. example: Smith phoneNumber: type: string description: The phone number of the individual associated with the address. example: '+491521111111' street: type: string description: The street name and number of the address. example: Maple Street 102/B postalCode: type: string description: The postal or ZIP code. example: '41460' city: type: string description: The city of the address. example: Berlin region: type: string description: The region of the address. example: Berlin country: type: string description: The country of the address, represented as a two-letter ISO 3166-1 alpha-2 country code. example: DE pattern: ^[A-Z]{2}$ ThreeDsAuthenticationDetails: type: object properties: requestUrl: type: string description: The URL where the consumer should be redirected in order to complete the 3D Secure authentication. example: https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=token requestMethod: type: string description: The redirect HTTP method. enum: - GET - POST PassthroughWalletDetails: type: object properties: fundingType: type: string description: The type of funding to be used by the provider for the agreement or the charge enum: - CREDIT - DEBIT CardNetworkTokenDetails: type: object properties: brand: type: string description: The card brand.
The value must be provided in uppercase. example: VISA minLength: 1 holderName: type: string description: The full name of the cardholder. example: John Smith minLength: 1 expiryMonth: type: integer format: int32 description: The two-digit expiration month of the token. example: 1 maximum: 12 minimum: 1 expiryYear: type: integer format: int32 description: The four-digit expiration year of the token. example: 2031 minimum: 2000 tokenNumber: type: string description: Unique identifier for the token. example: '5598830000009001' minLength: 1 eci: type: string description: A dynamic code to authorize payments using the token. example: '07' cryptogram: type: string description: The network token cryptogram example: CCADBxYzRTBBXXXXXXXYZa0AbZD= required: - brand - expiryMonth - expiryYear - holderName - tokenNumber PaymentInstrumentUpdate: discriminator: propertyName: type mapping: RAW_CARD: '#/components/schemas/RawCardInstrumentUpdate' properties: type: type: string required: - type MultiFactorAuthenticationMethod: allOf: - $ref: '#/components/schemas/AuthenticationMethod' - type: object properties: details: $ref: '#/components/schemas/MultiFactorAuthenticationDetails' description: The MULTI_FACTOR authentication details. type: type: string description: The MULTI_FACTOR authentication type. enum: - MULTI_FACTOR title: Authentication Method (MULTI_FACTOR) PaymentChargeAuthorizationResponse: type: object properties: id: type: string description: The authorization identifier. example: 5c019979-0751-469e-96e0-b67f1d95c577 amount: type: integer format: int64 description: The authorization amount in the payment charge currency's smallest unit. example: 1000 status: type: string description: The authorization status. enum: - AUTHORIZED - AUTHENTICATION_PENDING - PROVIDER_CONFIRMATION_PENDING - FAILED merchantPaymentChargeReference: type: string description: The merchant payment charge reference. example: 5c019979-0751-469e-96e0-b67f1d95c577 failure: $ref: '#/components/schemas/GatewayProcessingFailureResponse' description: The authorization processing failure if the authorization operation failed. schemeAuthorizationReference: type: string description: The scheme authorization reference post successful authorization, eg. for cards network transaction identifier (NTI) example: XPTO transactionLinkReference: type: string description: 'Transaction Link Reference or Id (ex: Mastercard TLID) is a unique identifier for a transaction, used by some card networks for transaction chain linking, this is in addition to Network Transaction Identifiers. This value will be present if it is returned by the financial network in the authorization response, and null otherwise.' example: atf3_8msFoZ6klReRDlQwn createdAt: type: string format: date-time description: The authorization creation timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' updatedAt: type: string format: date-time description: The authorization update timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' _links: $ref: '#/components/schemas/Links' readOnly: true AppNotificationAuthenticationSettingsDetails: type: object properties: instrumentProviderIdentity: type: string description: App identifier, for instance email, phone number example: '+34700000000' MockInstrument: allOf: - $ref: '#/components/schemas/PaymentInstrument' - type: object properties: details: type: object additionalProperties: type: string description: The MOCK payment details type: type: string description: The `MOCK` payment instrument type. enum: - MOCK title: Payment Instrument (MOCK) IndustryData: discriminator: propertyName: type properties: type: type: string required: - type PaymentChargeCaptureResponse: type: object properties: id: type: string description: The capture identifier. example: 5c019979-0751-469e-96e0-b67f1d95c577 amount: type: integer format: int64 description: The capture amount in the payment charge currency's smallest unit. example: 1000 status: type: string description: The capture status. enum: - CAPTURED - FAILED merchantCaptureReference: type: string description: The merchant provided capture reference. example: 5c019979-0751-469e-96e0-b67f1d95c577 failure: $ref: '#/components/schemas/GatewayProcessingFailureResponse' description: The capture processing failure if the capture operation failed. createdAt: type: string format: date-time description: The capture creation timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' updatedAt: type: string format: date-time description: The capture update timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' labels: type: object additionalProperties: type: string description: Custom labels associated with the capture. example: consumer_origin: GTM_Campaign _links: $ref: '#/components/schemas/Links' readOnly: true Link: type: object properties: href: type: string hreflang: type: string title: type: string type: type: string deprecation: type: string profile: type: string name: type: string templated: type: boolean OutOfScope: type: object properties: reason: type: string description: The 3DS out of scope reason, to be used to indicate the reason if the payment is out of scope of SCA enum: - MIT - MOTO - ONE_LEG_OUT - ANONYMOUS AppNotificationAuthenticationMethod: allOf: - $ref: '#/components/schemas/AuthenticationMethod' - type: object properties: details: $ref: '#/components/schemas/AppNotificationAuthenticationDetails' description: The APP_NOTIFICATION authentication details. type: type: string description: The APP_NOTIFICATION authentication type. enum: - APP_NOTIFICATION title: Authentication Method (APP_NOTIFICATION) PaymentInstrument: discriminator: propertyName: type mapping: RAW_CARD: '#/components/schemas/RawCardInstrument' BANK_ACCOUNT: '#/components/schemas/BankAccountInstrument' CARD_NETWORK_TOKEN: '#/components/schemas/CardNetworkTokenInstrument' PASSTHROUGH_WALLET: '#/components/schemas/PassthroughWalletInstrument' MOCK: '#/components/schemas/MockInstrument' BANCONTACT_ACCOUNT: '#/components/schemas/BancontactAccountInstrument' properties: type: type: string required: - type OrderItem: type: object properties: sku: type: string description: The Stock Keeping Unit (SKU) that uniquely identifies the product in the order. example: SKU-12345-WHITE category: type: string description: The category or classification of the product or service in the order. example: Clothing subCategory: type: string description: The sub category or classification of the product or service in the order. example: Sports Wear name: type: string description: The product or service name in the order. example: White T-Shirt minLength: 1 quantity: type: integer format: int32 description: The product or service quantity in the order. example: 1 amount: type: integer format: int64 description: The monetary value of the individual product or service, expressed in the smallest currency unit (e.g., cents for EUR). example: 1000 required: - amount - name - quantity AppIntentAuthenticationDetails: type: object properties: mobileIntentUri: type: string description: Intent URI to be used for app-to-app mobile flows. example: upiGlobal://pay?tr=123&from_app=true TravelIndustryData: allOf: - $ref: '#/components/schemas/IndustryData' - type: object properties: details: $ref: '#/components/schemas/TravelDetails' description: The travel industry specific details. type: type: string description: The `TRAVEL` industry data type. enum: - TRAVEL required: - details PaymentChargeRefundResponse: type: object properties: id: type: string description: The refund identifier. example: 5c019979-0751-469e-96e0-b67f1d95c577 amount: type: integer format: int64 description: The refund amount in the payment charge currency's smallest unit. example: 1000 status: type: string description: The refund status. enum: - REFUNDED - PENDING - FAILED merchantRefundReference: type: string description: The merchant provided refund reference. example: 5c019979-0751-469e-96e0-b67f1d95c577 refundReason: type: string description: The reason for the refund request. enum: - RETURN - DUPLICATE - FRAUD - CUSTOMER_REQUEST - PRE_DISPUTE - OTHER refundDescriptor: type: string description: The refund descriptor (arbitrary string). To provide consumer's bank account details example: 'Name: Jamie Shopper CPF:12345678909 Bank Name: Scotland Bank Agency Number: 1234 Account Number: 123456789' failure: $ref: '#/components/schemas/GatewayProcessingFailureResponse' description: The refund processing failure if the refund operation failed. createdAt: type: string format: date-time description: The refund creation timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' updatedAt: type: string format: date-time description: The refund update timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' _links: $ref: '#/components/schemas/Links' readOnly: true labels: type: object additionalProperties: type: string description: Custom labels associated with the refund. example: consumer_origin: GTM_Campaign BancontactAccountInstrument: allOf: - $ref: '#/components/schemas/PaymentInstrument' - type: object properties: details: $ref: '#/components/schemas/BancontactAccountDetails' description: The bancontact account details type: type: string description: The `BANCONTACT_ACCOUNT` payment instrument type. enum: - BANCONTACT_ACCOUNT title: Payment Instrument (BANCONTACT_ACCOUNT) CardNetworkTokenInstrument: allOf: - $ref: '#/components/schemas/PaymentInstrument' - type: object properties: details: $ref: '#/components/schemas/CardNetworkTokenDetails' description: The card network token details type: type: string description: The `CARD_NETWORK_TOKEN` payment instrument type. enum: - CARD_NETWORK_TOKEN title: Payment Instrument (CARD_NETWORK_TOKEN) Order: type: object properties: orderItems: type: array description: The list of order items. items: $ref: '#/components/schemas/OrderItem' shippingMethod: type: string description: 'Digital goods/services: VIRTUAL, Physical goods:TRACKED_DELIVERY, UNTRACKED_DELIVERY, IN_STORE_PICKUP, LOCKER_PICKUP or HYBRID' enum: - VIRTUAL - TRACKED_DELIVERY - UNTRACKED_DELIVERY - IN_STORE_PICKUP - LOCKER_PICKUP - HYBRID example: VIRTUAL shippingAddress: $ref: '#/components/schemas/Address' description: Defines the shipping address of the consumer. industryData: type: array description: Defines the enhanced industry data. items: discriminator: propertyName: type mapping: AIRLINE: '#/components/schemas/AirlineIndustryData' EDUCATION: '#/components/schemas/EducationIndustryData' TRAVEL: '#/components/schemas/TravelIndustryData' oneOf: - allOf: - $ref: '#/components/schemas/AirlineIndustryData' title: Industry Data - allOf: - $ref: '#/components/schemas/EducationIndustryData' title: Industry Data - allOf: - $ref: '#/components/schemas/TravelIndustryData' title: Industry Data orderReferenceNumber: type: string description: A merchant-defined identifier (e.g., invoice or order number) that remains the same across all payment attempts for the same order. example: order_ref_123 totalTaxAmount: type: integer format: int64 description: The total tax amount for the order.
Same currency as specified in `amount.currency`. example: 167 installmentPlan: $ref: '#/components/schemas/InstallmentPlan' description: The number of installments the consumer will split the payment into. BankAccountDetails: type: object properties: accountNumber: type: string description: The account number associated with the consumer’s bank account used for payment. example: '007123456' holderName: type: string description: The full name of the person or organization that owns the bank account. example: John Doe iban: type: string description: The International Bank Account Number used to identify a consumer’s bank account cross-border. example: DE75512108001245126199 swiftCode: type: string description: The SWIFT/BIC code uniquely identifies a specific bank or financial institution in international bank transfers. example: DEUTDEFF123 bankName: type: string description: The name of the bank where the account is held. example: My Bank bankCode: type: string description: A numeric or alphanumeric code that uniquely identifies a bank. example: '12341234' debitMandateId: type: string description: A unique identifier for the debit mandate. debitMandateIdMigrated: type: boolean description: A merchant-provided indicator specifying whether the payment instrument was migrated from a different provider. PassthroughWalletInstrument: allOf: - $ref: '#/components/schemas/PaymentInstrument' - type: object properties: details: $ref: '#/components/schemas/PassthroughWalletDetails' description: The passthrough wallet details type: type: string description: The PASSTHROUGH_WALLET payment instrument can be associated to payments where the money is debited directly from the card or bank account linked to it enum: - PASSTHROUGH_WALLET title: Payment Instrument (PASSTHROUGH_WALLET) InstallmentPlan: type: object properties: numberOfInstallments: type: integer format: int32 description: The number of installments the consumer will split the payment into. example: 1 feePaidBy: type: string description: 'Indicates which party bears the installment fees (e.g.: for BNPL installments).' enum: - MERCHANT - CONSUMER example: MERCHANT required: - numberOfInstallments EducationIndustryData: allOf: - $ref: '#/components/schemas/IndustryData' - type: object properties: details: $ref: '#/components/schemas/EducationDetails' description: The education industry specific details. type: type: string description: The `EDUCATION` industry data type. enum: - EDUCATION required: - details BankAccountInstrument: allOf: - $ref: '#/components/schemas/PaymentInstrument' - type: object properties: details: $ref: '#/components/schemas/BankAccountDetails' description: The bank account details type: type: string description: The `BANK_ACCOUNT` payment instrument type. enum: - BANK_ACCOUNT required: - details title: Payment Instrument (BANK_ACCOUNT) Money: type: object properties: value: type: integer format: int64 description: The monetary value to be charged or processed, expressed in the smallest currency unit (e.g., cents for EUR). example: 1000 currency: type: string description: The three-letter ISO 4217 currency code representing the currency in which the amount is denominated example: EUR maxLength: 3 minLength: 3 required: - currency - value ConfirmationRequest_2: type: object properties: authenticationResult: $ref: '#/components/schemas/AuthenticationResult_2' description: 'The outcome of processing the payment authentication challenge (eg: a payment provider generated token or a 3DS challenge response).' required: - authenticationResult GetAuthorizationsResponse: type: object properties: data: type: array description: The payment charge authorizations. items: $ref: '#/components/schemas/PaymentChargeAuthorizationResponse' _links: $ref: '#/components/schemas/Links' readOnly: true PaymentChargeVoidResponse: type: object properties: id: type: string description: The void identifier. example: 5c019979-0751-469e-96e0-b67f1d95c577 amount: type: integer format: int64 description: The void amount in the payment charge currency's smallest unit. example: 1000 status: type: string description: The void status. enum: - VOIDED - FAILED merchantVoidReference: type: string description: The merchant provided void reference. example: 5c019979-0751-469e-96e0-b67f1d95c577 failure: $ref: '#/components/schemas/GatewayProcessingFailureResponse' description: The void processing failure if the void operation failed. createdAt: type: string format: date-time description: The void creation timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' updatedAt: type: string format: date-time description: The void update timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' labels: type: object additionalProperties: type: string description: Custom labels associated with the void. example: consumer_origin: GTM_Campaign _links: $ref: '#/components/schemas/Links' readOnly: true PaymentChargeResponse: type: object properties: id: type: string description: The payment charge identifier. example: 5c019979-0751-469e-96e0-b67f1d95c577 paymentMethod: type: string description: The payment method which was used to process the payment charge. example: KLARNA_BNPL paymentMedium: type: string description: The payment medium. enum: - ECOMMERCE - MOTO - POS example: ECOMMERCE initiator: type: string description: The initiator of the charge enum: - CONSUMER - MERCHANT instrumentId: type: string description: The identifier of an existing payment instrument.
Instruments are used for account on file or recurring payments. example: instr_SNaRMvhYNFpXhEhgTVSed instrumentUpdated: type: boolean description: Indicates that the Payment Instrument has been updated during processing. Query Payment Instruments to retrieve the new details. agreementId: type: string description: The payment agreement identifier associated with the payment charge if payment is recurring. currency: type: string description: ISO 4217 3-letter code of the payment charge currency. example: EUR maxLength: 3 minLength: 3 country: type: string description: The payment charge country. example: DE paymentDescriptor: type: string description: The payment charge descriptor. example: PPRO - ORDER 1234 networkTransactionIdentifier: type: string deprecated: true description: The NTI (Network Transaction Identifier) example: XPTO initialTransactionLinkReference: type: string description: 'Transaction Link Reference or Id (ex: Mastercard TLID) is a unique identifier for a transaction, used by some card networks for transaction chain linking, this is in addition to Network Transaction Identifiers. Provide the initial TLID when creating the subsequent Merchant-Initiated-Transactions.' example: atf3_8msFoZ6klReRDlQwn status: type: string description: The payment charge status. enum: - AUTHORIZATION_PROCESSING - AUTHORIZATION_ASYNC - AUTHENTICATION_PENDING - CAPTURE_PENDING - CAPTURE_PROCESSING - CAPTURED - REFUND_PROCESSING - REFUNDED - VOID_PROCESSING - VOIDED - DISCARD_PROCESSING - DISCARDED - FAILED consumer: $ref: '#/components/schemas/Consumer' description: The payment charge consumer details. order: $ref: '#/components/schemas/Order' description: The payment charge order details. failure: $ref: '#/components/schemas/GatewayProcessingFailureResponse' description: The latest payment charge processing failure. authenticationMethods: type: array description: The available authentication methods for the authorization. items: oneOf: - $ref: '#/components/schemas/AppIntentAuthenticationMethod' - $ref: '#/components/schemas/AppNotificationAuthenticationMethod' - $ref: '#/components/schemas/MultiFactorAuthenticationMethod' - $ref: '#/components/schemas/RedirectAuthenticationMethod' - $ref: '#/components/schemas/ScanCodeAuthenticationMethod' - $ref: '#/components/schemas/ThreeDsAuthenticationMethod' authorizations: type: array description: The payment charge authorizations. items: $ref: '#/components/schemas/PaymentChargeAuthorizationResponse' captures: type: array description: The payment charge captures. items: $ref: '#/components/schemas/PaymentChargeCaptureResponse' refunds: type: array description: The payment charge refunds. items: $ref: '#/components/schemas/PaymentChargeRefundResponse' discards: type: array description: The payment charge discards. items: $ref: '#/components/schemas/PaymentChargeDiscardResponse' voids: type: array description: The payment charge voids. items: $ref: '#/components/schemas/PaymentChargeVoidResponse' createdAt: type: string format: date-time description: The payment charge creation timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' updatedAt: type: string format: date-time description: The payment charge update timestamp in ISO 8601 format. example: '2022-11-03T11:23:47.123Z' labels: type: object additionalProperties: type: string example: GTM_Campaign maxLength: 200 description: Custom labels associated with the payment charge. maxProperties: 50 propertyNames: type: string example: consumer_origin maxLength: 50 _links: $ref: '#/components/schemas/Links' readOnly: true AuthenticationResult_3: type: object properties: type: type: string description: The type of authentication result details: type: object additionalProperties: {} description: A map containing the authentication result details which format is understood by the payment processor of the associated payment method required: - details ConfirmationRequest_3: type: object properties: authenticationResult: $ref: '#/components/schemas/AuthenticationResult_3' description: 'The outcome of processing the payment authentication challenge (eg: a payment provider generated token or a 3DS challenge response).' required: - authenticationResult securitySchemes: bearer_token: type: http scheme: bearer x-refined-from: - ppro-payment-agreements-openapi.yml - ppro-payment-agreements.json - ppro-payment-charges-openapi.yml - ppro-payment-charges.json