Get Settlements

GET 
/v1/settlements/:settlementId

Click on Send API Request after entering the required data, to see how to lookup a Settlement using the ID returned in the response to the original request.

Request

Path Parameters

settlementId stringrequired

This is the ID returned in the response of the Process Payment request.

Responses

200

OK

Response Headers

• Content-Type

  string

application/json

Schema

Schema

id string

Possible values: <= 36 characters

This is the ID returned in the response. This ID can be used for future associated request.

paymentType string

Possible values: [CARD]

This is the payment type associated with the settlement used for this request.

availableToRefund number

Possible values: <= 99999999999

This is the remaining amount of the refund, in minor units.99.

childAccountNum string

Possible values: <= 10 characters

This is the child merchant account number. It is returned only if the transaction was processed via a master account.

txnTime date-time

This is the date and time the request was processed. For example: 2014-01-26T10:32:28Z

status string

Possible values: [RECEIVED, INITIATED, PENDING, FAILED, CANCELLED, EXPIRED, COMPLETED]

This is the status of the transaction request. Possible values are:

• RECEIVED – Our system has received the request and is waiting for the downstream processor’s response.

• INITIATED – The transaction was initiated with the downstream provider.

• PENDING - The transaction is awaiting the payment service provider's response.

• FAILED – The transaction failed, due to either an error or being declined.

• CANCELLED – The transaction request is cancelled.'

• EXPIRED – The transaction request is expired.

• COMPLETED – The transaction request is completed.

error

object

Details of the error.

code string

The error code. Also shown in the X-Application-Status-Code response header.

message string

A description of the error.

details string[]

Details of any parameter value errors.

fieldErrors

object[]

If applicable, this is a list of fields that have issues.

Array [

field string

Identifies the JSON request field.

error string

The problem associated with field.

]

riskReasonCode integer[]

An array of integers is returned, displaying the detailed Risk reason codes if your transaction was declined. It is returned only if your account is configured accordingly.

gatewayResponse

object

This is the read-only raw response returned by an acquirer. It is returned only if your account is configured accordingly.

id string

This is the response id returned by the processor

processor string

This is the processor code of the transaction at Paysafe side

code string

This is acquirer identification code, such as DJN, CRX, etc.

responseCode string

This is the raw response returned by the acquirer.

avsCode string

This is the raw AVS code returned by the acquirer.

avsResponse string

Possible values: [MATCH, MATCH_ADDRESS_ONLY, MATCH_ZIP_ONLY, NO_MATCH, NOT_PROCESSED, UNKNOWN]

This is the AVS response returned from the card issuer.

balanceResponse string

This is the balance remaining on a gift card, if a gift card was used for the original transaction.

mid string

This is the acquirer MID that was sent to the clearing house.

terminalId string

This is the merchant's terminal ID.

batchNumber string

This is the batch number.

seqNumber string

This is the merchant's sequence number.

effectiveDate string

This is the date of the bank deposit associated with the transaction.

financingType string

This is the type of financing offered.

plan string

This is the plan number for this financing transaction.

gracePeriod string

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

term string

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

responseId string

This is the response ID assigned by Credorax.

requestId string

This is the request ID assigned by Paysafe.

description string

This is a description of the response.

authCode string

This is the authorization code.

txnDateTime string

This is the transaction date and time.

referenceNbr string

This is the Bank net transaction ID/Merch Tran Ref

responseReasonCode string

This is the raw response reason code returned by Credorax.

cvvVerification string

Possible values: [MATCH, NO_MATCH, NOT_PROCESSED, UNKNOWN]

This is the response to the cvv submitted with the transaction request.

cvv2Result string

This is the raw cvv2 result code.

status string

This is the status of the transaction at the processor side.

orderId string

Unique NETELLER reference for the order.

profile

object

This is customer's profile details.

id string

The customer's profile id in the system. If this is present rest all other fields are not required.

status string

The status of customer in the system, returned in the response.

merchantCustomerId string

Possible values: <= 10 characters

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

Note: This value is mandatory when fundingTransaction is used.

locale stringrequired

Possible values: [en_US, fr_CA, en_GB, en_CA]

This indicates the customer's locale preference.

Note: Optional for GiroPay, Vippreferred-Direct-Registration. Not required for Paysafe Card Payouts.

firstName stringrequired

Possible values: <= 80 characters

This is the customer’s first name.

lastName stringrequired

Possible values: <= 80 characters

This is the customer’s last name.

email stringrequired

Possible values: <= 255 characters

This is the customer's email address.

phone string

Possible values: <= 40 characters

This is the customer's phone number.

Note: Optional for GiroPay. Not required for Paysafe Card Payouts.

dateOfBirth

object

This is the recipient's date of birth.

day numberrequired

Possible values: <= 31

This is the day of birth.

month numberrequired

Possible values: <= 12

This is the month of birth.

year numberrequired

Possible values: >= 1900

This is the year of birth.

mobile string

Possible values: <= 40 characters

Customer's mobile number.

gender string

Possible values: [M, F]

This field indicates the Customer's gender.

M - Male

F - Female

nationality string

Possible values: <= 30 characters

This field indicates the Customer's nationality.

identityDocuments

object[]

Array [

identityDocuments

object[]

required

This is array of 2 JSON objects.

• 1st object contains SSN

• 2nd object contains Identity document details.

Array [

anyOf

MOD1

type stringrequired

Possible values: [SOCIAL_SECURITY]

Default value: SOCIAL_SECURITY

Value will always be "SOCIAL_SECURITY" This is part of 1st JSON object.

documentNumber stringrequired

Possible values: <= 9 characters

The customer’s social security number.

MOD2

type stringrequired

Possible values: [PASSPORT, IDENTITY_CARD, DRIVING_LICENSE, SOCIAL_SECURITY, TAX_IDENTIFICATION, NATIONAL_IDENTITY, STATE_ID, MILITARY_ID, WORK_PERMIT, RESIDENCE_PERMIT, REGISTRATION_ID, ACRA, LICENSE_NUMBER, REGISTRATION_NUMBER, BUSINESS_TAX_IDENTIFICATION]

Identity documnent can be one of the allowed values:

documentNumber stringrequired

Possible values: >= 5 characters and <= 31 characters

The number associated with ID.

issuingCountry stringrequired

Value will always be "US".

issuingCountrySubdvision stringrequired

Possible values: <= 2 characters

Two letter state code. See State Codes

expiryDate

object

required

The expiration date associated with ID.

month numberrequired

Expiry year.

year numberrequired

Expiry month.

]

]

gatewayReconciliationId string

Possible values: <= 36 characters

It is the id which is common between paysafe and payment serivce provider.

liveMode boolean
This flag indicates the envrionment.
• true - Production
• false - Non-Production
updatedTime date-time

Indicates the last updated time for the resource.

statusTime date-time

Indicates the last updated time for the resource.

merchantRefNum stringrequired

Possible values: <= 255 characters

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

amount number

Possible values: <= 99999999999

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

dupCheck boolean

Default value: true

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

Note: This value defaults to true

splitpay

object[]

Array [

linkedAccount stringrequired

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

amount number

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.

percent number

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

]

airlineTravelDetails

object

Contains information about your airline travel.

Note: This object is only for Airline Merchants.

passengerName stringrequired

Possible values: <= 20 characters

Name of the passenger to whom the ticket was issued.

departureDate daterequired

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

origin stringrequired

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

Departure Airport Code: IATA Airport Code.

computerizedReservationSystem string

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

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.

ticket

object

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

ticketNumber stringrequired

Possible values: <= 20 characters

Airline ticket number

isRestrictedTicket boolean

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'

customerReferenceNumber string

Possible values: <= 20 characters

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

travelAgency

object

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

code string

Possible values: <= 8 characters

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

name string

Possible values: <= 25 characters

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

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).

carrierCode string

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

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

flightNumber string

Possible values: non-empty and <= 5 characters

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

serviceClass string

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

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

isStopOverAllowed boolean

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

• false - not allowed

• true - allowed

destination string

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

Destination Airport Code (IATA Airport Code).

fareBasis string

Possible values: non-empty and <= 6 characters

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

departureDate date

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

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).

carrierCode string

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

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

flightNumber string

Possible values: non-empty and <= 5 characters

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

serviceClass string

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

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

isStopOverAllowed boolean

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

• false - not allowed

• true - allowed

destination string

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

Destination Airport Code (IATA Airport Code).

fareBasis string

Possible values: non-empty and <= 6 characters

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

departureDate date

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

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).

carrierCode string

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

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

flightNumber string

Possible values: non-empty and <= 5 characters

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

serviceClass string

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

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

isStopOverAllowed boolean

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

• false - not allowed

• true - allowed

destination string

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

Destination Airport Code (IATA Airport Code).

fareBasis string

Possible values: non-empty and <= 6 characters

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

departureDate date

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

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).

carrierCode string

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

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

flightNumber string

Possible values: non-empty and <= 5 characters

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

serviceClass string

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

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

isStopOverAllowed boolean

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

• false - not allowed

• true - allowed

destination string

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

Destination Airport Code (IATA Airport Code).

fareBasis string

Possible values: non-empty and <= 6 characters

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

departureDate date

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

passengerNameRecord string

Possible values: <= 10 characters

The airline company uses the passengerNameRecord as a reservation number.

additionalBookingReference string

Possible values: <= 50 characters

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

totalFare number

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

totalFee number

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

totalTaxes number

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

passengers string

Information about the passengers reserved tickets with the same transaction.

Example (from schema)

{
  "id": "25f6dadf-176a-415f-95c9-6ff39ff697ba",
  "paymentType": "CARD",
  "availableToRefund": 0,
  "childAccountNum": "1234567898",
  "txnTime": "2024-11-12T16:34:36.295Z",
  "status": "RECEIVED",
  "error": {
    "code": "5068",
    "message": "Field error(s)",
    "details": [
      "Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected."
    ],
    "fieldErrors": [
      {
        "field": "accountId",
        "error": "AccountId is missing in the request. If multiple accounts are registered with same currency, accountId is mandatory."
      }
    ]
  },
  "riskReasonCode": [
    0
  ],
  "gatewayResponse": {
    "id": "string",
    "processor": "string",
    "code": "string",
    "responseCode": "string",
    "avsCode": "string",
    "avsResponse": "MATCH",
    "balanceResponse": "string",
    "mid": "string",
    "terminalId": "string",
    "batchNumber": "string",
    "seqNumber": "string",
    "effectiveDate": "string",
    "financingType": "string",
    "plan": "string",
    "gracePeriod": "string",
    "term": "string",
    "responseId": "string",
    "requestId": "string",
    "description": "string",
    "authCode": "string",
    "txnDateTime": "string",
    "referenceNbr": "string",
    "responseReasonCode": "string",
    "cvvVerification": "MATCH",
    "cvv2Result": "string",
    "status": "string",
    "orderId": "string",
    "profile": {
      "id": "string",
      "status": "string",
      "merchantCustomerId": "string",
      "locale": "en_US",
      "firstName": "Venkata Suresh",
      "lastName": "Chagalamarri",
      "email": "paysafe@gmail.com",
      "phone": "1234567891",
      "dateOfBirth": {
        "day": 6,
        "month": 5,
        "year": 1998
      },
      "mobile": "9846573804",
      "gender": "M",
      "nationality": "Indian",
      "identityDocuments": [
        {
          "identityDocuments": [
            {
              "type": "SOCIAL_SECURITY",
              "documentNumber": "SSN123456"
            },
            {
              "type": "PASSPORT",
              "documentNumber": "1234567",
              "issuingCountry": "USA",
              "issuingCountrySubdvision": "SA",
              "expiryDate": {
                "month": 12,
                "year": 2022
              }
            }
          ]
        }
      ]
    }
  },
  "gatewayReconciliationId": "a5c80e61-e747-455f-843d-2b9526f9963e",
  "liveMode": true,
  "updatedTime": "2023-01-19T10:48:04Z",
  "statusTime": "2023-01-19T10:48:04Z",
  "merchantRefNum": "string",
  "amount": 0,
  "dupCheck": true,
  "splitpay": [
    {
      "linkedAccount": "123124124",
      "amount": 505,
      "percent": 5
    }
  ],
  "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"
  }
}

Look Up Settlement

{
  "id": "8d951743-78e5-4fa5-aa15-2c42f0c05228",
  "paymentType": "PAYSAFECASH",
  "merchantRefNum": "a9318b525273ee3cda79a2f947a9",
  "currencyCode": "USD",
  "txnTime": "2023-01-20T04:20:31Z",
  "status": "COMPLETED",
  "gatewayReconciliationId": "6eac96d8-b42e-4bc2-b0c8-b0cf19318113",
  "amount": 500,
  "liveMode": false,
  "updatedTime": "2023-01-20T04:20:31Z",
  "statusTime": "2023-01-20T04:20:31Z",
  "availableToRefund": 500,
  "gatewayResponse": {
    "id": "6eac96d8-b42e-4bc2-b0c8-b0cf19318113",
    "processor": "PAYSAFECASH"
  }
}

Loading...