Skip to main content

paymentRequest

merchantRefNumstringrequired

This is the merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request.

Possible values: <= 255 characters

Example: 445186567390019700
amountnumberrequired

This is the amount of the request, in minor units. For example, to process US $10.99, this value should be 1099.

Note: The amount specified in the Payment request must match the amount specified in the Payment Handle request from which the paymentHandleToken is taken.

Possible values: <= 99999999999

Example: 500
dupCheckboolean

This validates that this request is not a duplicate. A duplicate request is when the merchantRefNum has already been used in a previous request within the past 90 days.

settleWithAuthboolean

This indicates whether the request is an Authorization only (no Settlement), or a Purchase (Authorization and Settlement).

  • false – The request is not settled

  • true – The request is settled

Note: Defaults to true.

preAuthboolean

This indicates whether the Authorization request should be sent as a Pre-Authorization.

Note: You should use the preAuth element in cases where you are not sure that you can fully settle the Authorization within 4 days. Contact your account manager for more information.

partialAuth object

This is an authorization that is approved for an amount lower than the requested amount. The remainder of the amount could be paid by other means.

requestedboolean

This specifies whether or not a partial authorization was requested.

Example: true
amountDuenumber

This is the amount of the full authorization that is not covered by the Payment request.

Possible values: <= 99999999999

Example: 1000
originalAmountnumber

This is the actual amount of the full authorization.

Possible values: <= 99999999999

Example: 2000
paymentHandleTokenstringrequired

This is the payment token generated by Paysafe that will be used for the Payment request.

Possible values: <= 36 characters

Example: SAJyTBzCvS8YHwwb
customerIpstring

This is the customer's IP address.

Possible values: <= 39 characters

Example: 172.0.0.1
descriptionstring

This is a description of the transaction, provided by the merchant.

Possible values: <= 255 characters

Example: Magazine subscription
currencyCodestringrequired

This is the currency of the merchant account, e.g., USD or CAD, returned in the request response. See Currency Codes.

Note: The currencyCode specified in the Payment request must match the currencyCode specified in the Payment Handle request from which the paymentHandleToken is taken.

Possible values: <= 3 characters

Example: USD
level2level3 object

Level 2 and Level 3 (L2/L3) credit card processing refers to certain B2B card transactions for which the merchant might be eligible for lower credit card interchange rates. The lower rates may be available for merchants who provide more detailed information when processing card-not-present transactions. In order to be eligible for L2/L3 transactions:

  • Your merchant account must be properly configured by Paysafe.

  • The BIN of the credit card used for the transaction must be eligible –typically,these are government-issued credit cards.

Note: Not all processing gateways support this parameter. Contact your accountmanager for more information.

exemptLocalTaxboolean

This indicates whether or not local tax is exempted for the request. If set to true, then the localTaxAmount parameter will be ignored.

Note: This value defaults to false

Default value: false
Example: true
localTaxAmountnumber

This is the local sales tax applied to the purchase.

Example: 1500
nationalTaxAmountnumber

This is the national tax included in the transaction amount.

Possible values: <= 99999999999

Example: 0
freightAmountnumber

This is the freight or shipping portion of the total transaction amount.

Possible values: <= 99999999999

Example: 0
dutyAmountnumber

This is the duty associated with the import of the purchased goods.

Possible values: <= 99999999999

Example: 0
destinationZipstring

This is the postal/zip code of the address to which the purchased goods will be delivered. This field can be identical to the shipFromZip if the customer is present and takes immediate possession of the goods.

Possible values: <= 10 characters

Example: 90210
destinationCountrystring

This is the country to which the goods are being shipped. See Country Codes.

Possible values: <= 2 characters

Example: US
shipFromZipstring

This is the postal/zip code of the address from which the purchased goods are being shipped.

Possible values: <= 10 characters

Example: 90211
lineItems object

This is more detailed information about the items that are being purchased for Level2Level3 merchants

descriptionstring

This is a description of the item(s) being purchased.

Possible values: <= 50 characters

Example: Disney Cruise Line
productCodestring

This is a merchant-defined description code of the item being purchased.

Possible values: <= 12 characters

Example: DCL
quantitynumber

This is the quantity of the item.

Note: Max 4 decimals is allowed.

Possible values: <= 99999999999

Example: 4
unitAmountnumber

This is the unit price of the item being purchased, in minor units. The currency will be based on the account setting.

Possible values: <= 99999999999

Example: 120000
taxRatenumber

This is the tax rate used to calculate the tax amount. For example, if the tax rate is 10.5%, this value should be 10.5.

Note: Max 2 decimals allowed.

Possible values: <= 100

Example: 5
taxAmountnumber

This is the amount of any value-added taxes that can be associated with the purchased item, in minor units. The currency will be based on the account setting.

Note: Our system will not validate the accuracy of this value. The merchant's application must calculate this value correctly.

Possible values: <= 99999999999

Example: 24000
totalAmountnumber

This is the total amount of the line item, typically calculated as price multiplied by quantity, in minor units. The currency is based on the account setting.

Note: Our system will not validate the accuracy of this value. The merchant''s application must calculate this value correctly.

Possible values: <= 99999999999

accordD object

These are parameters for financing plans supported for certain merchant configurations. Include this element only when instructed to do so by your account manager.

Note: Not all processing gateways support this parameter. Contact your account manager for more information.

financingTypestring

This is the type of financing offered.

  • DEFERRED_PAYMENT – Deferred payment financing.
  • EQUAL_PAYMENT – Equal payment financing

Possible values: [DEFERRED_PAYMENT, EQUAL_PAYMENT]

planstring

This is the plan number for this financing transaction.

Possible values: <= 3 characters

Example: 124
gracePeriodnumber

This is the grace period, in months, associated with deferred payment transactions.

Possible values: <= 99

Example: 12
termnumber

This is the number of payments, in months, for equal payment transactions.

Possible values: <= 99

Example: 12
recipient object

The recipient is deemed to be the person or party who has the contractual relationship with the merchant / financial institution. This may be different from the cardholder, e.g., in the case of a parent topping up a child's savings account. Therefore, the fields should not be collected on the same page as cardholder information, but instead be passed in the background from the merchant's records.

Note: You can include recipient elements in your authorization request only if your Merchant Category Code is 6012 and your registered trading address is in the United Kingdom. All fields are optional. However, scheme fines may apply if data is consistently not supplied and chargebacks persist. If you have any questions, contact your account manager. If you are using a payment token for an Authorization request and there is already recipient data for the consumer profile associated with the payment token, then if you include the recipient object in the Authorization, this data will override the recipient data already in the profile.

If you look up an authorization request that used the visaAdditionalAuthData parameter (now deprecated), the response will contain the relevant data in both the recipient and the visaAdditionalAuthData objects.

dateOfBirth object

This is the recipient's date of birth.

daynumberrequired

This is the day of birth.

Possible values: <= 31

Example: 6
monthnumberrequired

This is the month of birth.

Possible values: <= 12

Example: 5
yearnumberrequired

This is the year of birth.

Possible values: >= 1900

Example: 1998
zipstring

This is the zip/postal code of the recipient.

Note: The last 3 characters are not sent to the banking network.

Possible values: <= 10 characters

Example: CB24 9AD
lastNamestring

This is the recipient's last name.

Note: Only the first 6 characters are sent to the banking network.

Possible values: <= 255 characters

Example: Chagalamarri
accountNumberstring

This is the recipient's account number, e.g., a loan agreement number or customer ID. In the case where the recipient account is a prepaid card, the card number may be sent in full.

Note: Only the first 6 and last 4 characters are sent to the banking network and will be masked accordingly within the back office and any other reports, to comply with PCI regulations.

Possible values: <= 25 characters

Example: ABC1234567890
splitpay object

This object should be used only for Splitpay transactions only, an array containing the linked accounts and the amount shared with each. You must include either amount or percent. However, you cannot include both values.

linkedAccountstringrequired

This is the ID of the linked account. This account must already be linked to the merchant account.

Example: 123124124
amountnumber

This is the amount to transfer to the linked account in minor currency units. The total amount to all linked accounts cannot exceed the transaction total.

Example: 505
percentnumber

This is the percentage of the total transaction amount to transfer to that account. The total percentage to all linked accounts cannot exceed 100%.

Example: 5
storedCredentialDetails object

The storedCredential object is used to identify [authorization requests] that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. Stored credentials can be used in two cases:

  • Using a payment token – An authorization request that uses a paymentToken from the [Customer Vault API]

  • Using a card number – An authorization request that uses a credit card number stored by the merchant.

Notes:

  • If you use a paymentToken in the authorization request but do not include the storedCredential object, Paysafe will provide default information taken from Customer Vault data.

  • You cannot include both the storedCredential object and the recurring parameter in the same authorization request. Paysafe recommends using the storedCredential object.

  • The cvv parameter of the [card object] is required when the occurrence parameteris set to INITIAL. However, cvv is not required when the occurrence parameter is set to SUBSEQUENT.

  • The storedCredential object cannot be used for Apple Pay or Google Pay transactions.

typestring

This specifies the type of request being made. Possible values are:

  • ADHOC – Ad hoc consumer-initiated request

  • TOPUP – Unscheduled merchant-iniitated request when a consumer balance is below a set limit.

  • RECURRING – Scheduled, merchant-initiated recurring request.

Note: This value defaults to ADHOC.

Possible values: [ADHOC, TOPUP, RECURRING]

Default value: ADHOC
occurrencestring

This specifies whether this stored credential request is initial or recurring. Possible values are:

  • INITIAL – Used when this is the first time the consumer uses this credit card.

  • SUBSEQUENT – Used when the consumer uses this credit card for subsquent requests.

Note: This value defaults to INITIAL.

Possible values: [INITIAL, SUBSEQUENT]

Default value: INITIAL
initialTransactionIdstring

Id of the initial Recurring Payment transaction. This id should be stored from the auth response of the transaction indicated as initial with the following: type=RECURRING/TOPUP, occurrence=INITIAL. This reference should be provided when:

  • type = RECURRING and occurrence = SUBSEQUENT -type = TOPUP and occurrence = SUBSEQUENT

Note: This reference is a must to meet PSD 2 authentication process requirements for merchant initiated transactions successfully.

Possible values: <= 36 characters

externalInitialTransactionIdstring

Id of the initial Recurring Payment transaction in case this transaction was processed through external PSP. This reference should be provided only when:

  • type=RECURRING and occurrence=SUBSEQUENT
  • type=TOPUP and occurrence=SUBSEQUENT Note: This reference cannot be provided along with initialTransactionId.

Possible values: <= 256 characters

airlineTravelDetails object

Contains information about your airline travel.

Note: This object is only for Airline Merchants.

passengerNamestringrequired

Name of the passenger to whom the ticket was issued.

Possible values: <= 20 characters

Example: Venkata Suresh
departureDatedaterequired

Date of passenger’s departure. Date format = YYYY-MM-DD, ISO 8601 expected. For example 2022-12-20.

Example: 2022-12-20
originstringrequired

Departure Airport Code: IATA Airport Code.

Possible values: >= 3 characters and <= 3 characters

Example: SXF
computerizedReservationSystemstring

Indicates the computerized reservation system used to make the reservation and purchase the ticket. For tickets purchased in Germany, this field should one of these codes:

  • STRT - Start

  • PARS - TWA

  • DATS - Delta

  • SABR - Sabre

  • DALA - Covia-Apollo

  • BLAN - Dr. Blank

  • DERD - DER

  • TUID - TUI

Note: Required only if the ticket is purchased in Germany. Otherwise it can be omitted.

Possible values: [STRT, PARS, DATS, SABR, DALA, BLAN, DERD, TUID]

Example: DATS
ticket object

Information about the Airline Ticket Number and if the ticket is restricted.

ticketNumberstringrequired

Airline ticket number

Possible values: <= 20 characters

Example: 1234567891011
isRestrictedTicketboolean

Indicates whether this ticket is non-refundable. This entry should be supplied on CPS/Passenger Transport 1 or 2 transactions if the ticket was purchased as a non-refundable ticket. Valid values are:

  • false - No restriction (default)

  • true - Restricted (non-refundable) ticket'

customerReferenceNumberstring

Contains the code that the cardholder supplied to the card acceptor.

Possible values: <= 20 characters

Example: 10987654321
travelAgency object

Information about the travel agency if the ticket was issued by a travel agency.

codestring

Code identifying travel agency if the ticket was issued by a travel agency..

Possible values: <= 8 characters

Example: MY AGENT
namestring

Information about the travel agency if the ticket was issued by a travel agency.

Possible values: <= 25 characters

Example: MYAGENT347
tripLegs object

A grouping of four separate trip segments. Each leg contains detailed itinerary information.

leg1 object

Contains detailed itinerary information for one of the trip legs

flight object

Operating Carrier Code and the Number of the airline flight to be taken on Leg of the trip (excluding the carrier code).

carrierCodestring

Operating Carrier Code; the standard abbreviation code indicating name of the operating carrier like United Airlines, Jet Blue, etc.

Possible values: >= 2 characters and <= 2 characters

Example: LH
flightNumberstring

Number of the airline flight to be taken on Leg of the trip excluding the carrier code.

Possible values: non-empty and <= 5 characters

Example: 0799
serviceClassstring

Indicates service class (first class, business class, etc.). Example values (not limited to):

  • F - first class

  • J - business class

  • W - premium economy class

  • Y - economy class

Possible values: non-empty and <= 1 characters, [F, J, W, Y]

Example: F
isStopOverAllowedboolean

Indicates whether a stopover is allowed on this ticket. Valid values are:

  • false - not allowed

  • true - allowed

destinationstring

Destination Airport Code (IATA Airport Code).

Possible values: >= 3 characters and <= 3 characters

Example: SOF
fareBasisstring

Contains a Fare Basis Code for Leg that carriers assign to a particular ticket type, such as business class or discounted/nonrefundable.

Possible values: non-empty and <= 6 characters

Example: VMAY
departureDatedate

Date of passenger’s departure for this leg. Date format = YYYY-MM-DD, ISO 8601 expected. For example, 2014-01-26

Example: 2022-12-20
leg2 object

Contains detailed itinerary information for one of the trip legs

flight object

Operating Carrier Code and the Number of the airline flight to be taken on Leg of the trip (excluding the carrier code).

carrierCodestring

Operating Carrier Code; the standard abbreviation code indicating name of the operating carrier like United Airlines, Jet Blue, etc.

Possible values: >= 2 characters and <= 2 characters

Example: LH
flightNumberstring

Number of the airline flight to be taken on Leg of the trip excluding the carrier code.

Possible values: non-empty and <= 5 characters

Example: 0799
serviceClassstring

Indicates service class (first class, business class, etc.). Example values (not limited to):

  • F - first class

  • J - business class

  • W - premium economy class

  • Y - economy class

Possible values: non-empty and <= 1 characters, [F, J, W, Y]

Example: F
isStopOverAllowedboolean

Indicates whether a stopover is allowed on this ticket. Valid values are:

  • false - not allowed

  • true - allowed

destinationstring

Destination Airport Code (IATA Airport Code).

Possible values: >= 3 characters and <= 3 characters

Example: SOF
fareBasisstring

Contains a Fare Basis Code for Leg that carriers assign to a particular ticket type, such as business class or discounted/nonrefundable.

Possible values: non-empty and <= 6 characters

Example: VMAY
departureDatedate

Date of passenger’s departure for this leg. Date format = YYYY-MM-DD, ISO 8601 expected. For example, 2014-01-26

Example: 2022-12-20
leg3 object

Contains detailed itinerary information for one of the trip legs

flight object

Operating Carrier Code and the Number of the airline flight to be taken on Leg of the trip (excluding the carrier code).

carrierCodestring

Operating Carrier Code; the standard abbreviation code indicating name of the operating carrier like United Airlines, Jet Blue, etc.

Possible values: >= 2 characters and <= 2 characters

Example: LH
flightNumberstring

Number of the airline flight to be taken on Leg of the trip excluding the carrier code.

Possible values: non-empty and <= 5 characters

Example: 0799
serviceClassstring

Indicates service class (first class, business class, etc.). Example values (not limited to):

  • F - first class

  • J - business class

  • W - premium economy class

  • Y - economy class

Possible values: non-empty and <= 1 characters, [F, J, W, Y]

Example: F
isStopOverAllowedboolean

Indicates whether a stopover is allowed on this ticket. Valid values are:

  • false - not allowed

  • true - allowed

destinationstring

Destination Airport Code (IATA Airport Code).

Possible values: >= 3 characters and <= 3 characters

Example: SOF
fareBasisstring

Contains a Fare Basis Code for Leg that carriers assign to a particular ticket type, such as business class or discounted/nonrefundable.

Possible values: non-empty and <= 6 characters

Example: VMAY
departureDatedate

Date of passenger’s departure for this leg. Date format = YYYY-MM-DD, ISO 8601 expected. For example, 2014-01-26

Example: 2022-12-20
leg4 object

Contains detailed itinerary information for one of the trip legs

flight object

Operating Carrier Code and the Number of the airline flight to be taken on Leg of the trip (excluding the carrier code).

carrierCodestring

Operating Carrier Code; the standard abbreviation code indicating name of the operating carrier like United Airlines, Jet Blue, etc.

Possible values: >= 2 characters and <= 2 characters

Example: LH
flightNumberstring

Number of the airline flight to be taken on Leg of the trip excluding the carrier code.

Possible values: non-empty and <= 5 characters

Example: 0799
serviceClassstring

Indicates service class (first class, business class, etc.). Example values (not limited to):

  • F - first class

  • J - business class

  • W - premium economy class

  • Y - economy class

Possible values: non-empty and <= 1 characters, [F, J, W, Y]

Example: F
isStopOverAllowedboolean

Indicates whether a stopover is allowed on this ticket. Valid values are:

  • false - not allowed

  • true - allowed

destinationstring

Destination Airport Code (IATA Airport Code).

Possible values: >= 3 characters and <= 3 characters

Example: SOF
fareBasisstring

Contains a Fare Basis Code for Leg that carriers assign to a particular ticket type, such as business class or discounted/nonrefundable.

Possible values: non-empty and <= 6 characters

Example: VMAY
departureDatedate

Date of passenger’s departure for this leg. Date format = YYYY-MM-DD, ISO 8601 expected. For example, 2014-01-26

Example: 2022-12-20
passengerNameRecordstring

The airline company uses the passengerNameRecord as a reservation number.

Possible values: <= 10 characters

Example: ABCDE12345
additionalBookingReferencestring

BookingReference field. Typically used for the PNR, but should allow an airline to specify any other reference if they feel fit.

Possible values: <= 50 characters

totalFarenumber

Total fare for all legs on the ticket, excluding taxes and fees. If multiple tickets are purchased, this is the total fare for all tickets

totalFeenumber

Total fee for all legs on the ticket. If multiple tickets are purchased, this is the total fee for all tickets.

totalTaxesnumber

Total taxes for all legs on the ticket. If multiple tickets are purchased, this is the total taxes for all tickets.

passengersstring

Information about the passengers reserved tickets with the same transaction.

fundingTransaction object

The fundingTransaction object is used to identify authorization requests that are categorized as funding transactions by the merchant in order to provide information. It can be used by merchants registered with MCC 4829, 6012, 6051 or 6540.

  • SVDW_FUNDS_TRANSFER - Applicable for 4829, 6012 and 6540.

  • SDW_WALLET_TRANSFER - Applicable for 6051 only.

Notes:

  • If you want to support funding transactions for additional MCCs, please contact Paysafe's operational support.

  • If you send fundingTransaction type value in the authorization request, but youracquirer doesn't support funding transactions or your account is not configured, the transaction will be declined with error: 5040.

  • If you send fundingTransaction type in the authorization request with value not applicable for your MCC, the transaction will be declined with error: 3068.

  • If you send fundingTransaction type in the authorization request with value not part of the list below, the transaction will be declined with error: 5068.

  • If you send fundingTransaction type value in the authorization request and your account is configured to process funding transactions, but you are not registered to process funding transactions to specific card brand, the transaction will be successfully processed and the processorAppliedType in the response will be "NOT_APPLIED".

  • If you send fundingTransaction type value in the authorization request and your account is configured to process funding transactions and you are registered to process funding transactions to the respective card brand, the transaction will be successfully processed and the processorAppliedType will be equal to the fundingTransaction type, provided in the request.

  • Suppose you send fundingTransaction type value in the authorization request, andyour account is configured to process funding transactions. You are registered to process funding transactions to the respective card brand. In that case, the transaction will be successfully processed, and the processorAppliedType will be equal to the fundingTransaction type provided in the request.

  • To Process the transaction the below fields are mandatory in transaction:

Profile

  • firstName
  • lastName
  • merchantCustomerId

Billing Details

  • street
  • city
  • state (If US or Canada)
  • country
  • Zip
typestring

The fundingTransaction type is included in the request and set by the merchant.Supported funding transaction type values:

Possible values: [SVDW_FUNDS_TRANSFER, SDW_WALLET_TRANSFER]

processorAppliedTypestring

The fundingTransaction processorAppliedType value is chosen by Paysafe based on the merchant configuration. It is either equal to the funding transaction type sent by the merchant or "NOT_APPLIED" in case the merchant is not registered in the relevant card scheme system. The processorAppliedType can be seen in the auth response.Supported funding transaction processorAppliedType values:

Possible values: [SVDW_FUNDS_TRANSFER, SDW_WALLET_TRANSFER, NOT_APLLIED]

paymentRequest
{
"merchantRefNum": "445186567390019700",
"amount": 500,
"dupCheck": true,
"settleWithAuth": true,
"preAuth": true,
"partialAuth": {
"requested": true,
"amountDue": 1000,
"originalAmount": 2000
},
"paymentHandleToken": "SAJyTBzCvS8YHwwb",
"customerIp": "172.0.0.1",
"description": "Magazine subscription",
"currencyCode": "USD",
"level2level3": {
"exemptLocalTax": true,
"localTaxAmount": 1500,
"nationalTaxAmount": 0,
"freightAmount": 0,
"dutyAmount": 0,
"destinationZip": "90210",
"destinationCountry": "US",
"shipFromZip": "90211",
"lineItems": {
"description": "Disney Cruise Line",
"productCode": "DCL",
"quantity": 4,
"unitAmount": 120000,
"taxRate": 5,
"taxAmount": 24000,
"totalAmount": 0
}
},
"accordD": {
"financingType": "DEFERRED_PAYMENT",
"plan": "124",
"gracePeriod": 12,
"term": 12
},
"recipient": {
"dateOfBirth": {
"day": 6,
"month": 5,
"year": 1998
},
"zip": "CB24 9AD",
"lastName": "Chagalamarri",
"accountNumber": "ABC1234567890"
},
"splitpay": {
"linkedAccount": "123124124",
"amount": 505,
"percent": 5
},
"storedCredentialDetails": {
"type": "ADHOC",
"occurrence": "INITIAL",
"initialTransactionId": "string",
"externalInitialTransactionId": "string"
},
"airlineTravelDetails": {
"passengerName": "Venkata Suresh",
"departureDate": "2022-12-20",
"origin": "SXF",
"computerizedReservationSystem": "DATS",
"ticket": {
"ticketNumber": "1234567891011",
"isRestrictedTicket": true
},
"customerReferenceNumber": "10987654321",
"travelAgency": {
"code": "MY AGENT",
"name": "MYAGENT347"
},
"tripLegs": {
"leg1": {
"flight": {
"carrierCode": "LH",
"flightNumber": "0799"
},
"serviceClass": "F",
"isStopOverAllowed": true,
"destination": "SOF",
"fareBasis": "VMAY",
"departureDate": "2022-12-20"
},
"leg2": {
"flight": {
"carrierCode": "LH",
"flightNumber": "0799"
},
"serviceClass": "F",
"isStopOverAllowed": true,
"destination": "SOF",
"fareBasis": "VMAY",
"departureDate": "2022-12-20"
},
"leg3": {
"flight": {
"carrierCode": "LH",
"flightNumber": "0799"
},
"serviceClass": "F",
"isStopOverAllowed": true,
"destination": "SOF",
"fareBasis": "VMAY",
"departureDate": "2022-12-20"
},
"leg4": {
"flight": {
"carrierCode": "LH",
"flightNumber": "0799"
},
"serviceClass": "F",
"isStopOverAllowed": true,
"destination": "SOF",
"fareBasis": "VMAY",
"departureDate": "2022-12-20"
}
},
"passengerNameRecord": "ABCDE12345",
"additionalBookingReference": "string",
"totalFare": 0,
"totalFee": 0,
"totalTaxes": 0,
"passengers": "string"
},
"fundingTransaction": {
"type": "SVDW_FUNDS_TRANSFER",
"processorAppliedType": "SVDW_FUNDS_TRANSFER"
}
}