Skip to main content

Create Settle (Approved Auth)

POST 
/payments/{payment-id}/settles

Creates a settle (capture) request following a previously approved Auth transaction.

Request​

Path Parameters

    payment-id stringrequired

    Payment ID generated by REST API

    Example: 49900038994789921

Header Parameters

    idempotency-key string

    Idempotency Key for the request

    Example: 31f9952c-0058-458b-8244-4ae110ef1556

Body

required

    processingEntityId uuidrequired

    Processing entityId provided by Nuvei.

    merchantTransactionId string

    ID of the transaction in the merchant system.

    Possible values: <= 45 characters

    amount number

    The transaction amount.

    productId string

    A free text field used to identify the product/service sold. If this parameter is left empty, need to insert a concatenation of all item names. It's not related to rebilling system product id. Risk rules and traffic management rules are usually built based on this field value.

    Possible values: <= 50 characters

    siteNameOverride string

    Possible values: <= 255 characters

    custom

    object

    property name* string

    urlDetails

    object

    With this class, a merchant can dynamically provide possible URLs to which the end user is redirected after a payment is made, as well as a dynamic URL for DMNs.

    webhookUrl string

    The URL to which notifications for outcome of the financial transactions is sent.

    successUrl string

    The URL to which the end user is redirected for a successful transaction with an APM.

    failureUrl string

    The URL to which the end user is redirected for an unsuccessful transaction with an APM.

    pendingUrl string

    The URL to which the end user is redirected for a pending transaction with an APM.

    returnToAppUrl string

    The URL to which the end user is redirected in case of a successful transaction with an APM that shuold open in an external browser.

    totalSettleCount int32

    An optional parameter that represents the total Settle transactions to be executed against the Auth transaction.

    Possible values: >= 1

    Example: 2

    extendedData

    object

    lodging

    object

    reservationDetails

    object

    purchaseId string

    Merchant reference

    customerServicePhone string

    Customer service phone number

    noShowIndicator NoShowIndicator (string)

    Possible values: [NotApplicable, NoShow]

    extraCharges LodgingExtraCharges (string)

    Possible values: [PositionNotUsed, Reserved, Restaurant, GiftShop, MiniBar, Telephone, Other, Laundry]

    checkInDate string

    Check-in date in YYYYMMDD format

    checkOutDate string

    Check-out date in YYYYMMDD format

    propertyPhone string

    Property phone number

    lodgingName string

    Hotel or cruise name

    lodgingType LodgingType (string)

    Possible values: [Cruise, Hotel]

    totalAuthAmount number

    Total authorized amount

    rooms

    object

    rate number

    Daily room rate

    nights integer

    Total number of nights

    passengerDetails

    object[]

    List of passengers

  • Array [

    • fullName string

    Full name of the passenger

  • ]

    • segments

    object[]

    Departure leg dates, up to 4

    Possible values: <= 4

  • Array [

    • departureDate string

    Departure date in YYYYMMDD format

  • ]

    • airlines

    object

    pnrCode string

    Passenger Name Record identifier in airline reservation system

    bookingSystemUniqueId string

    Unique reservation identifier in the GDS

    computerizedReservationSystem string

    CRS name, e.g. Amadeus, Sabre, Galileo

    ticketNumber string

    Primary airline ticket number

    documentType string

    Document type, typically TKT (e-ticket) or OT

    flightDateUtc date-time

    UTC date/time of first flight leg

    issueDateUtc date-time

    UTC timestamp of last ticket issue or reissue

    travelAgencyCode string

    IATA agency code

    travelAgencyName string

    Travel agency name

    travelAgencyInvoiceNumber string

    Agency invoice reference

    travelAgencyPlaneName string

    Aircraft type ICAO code (e.g., B737)

    restrictedTicketIndicator RestrictedTicketIndicator (string)

    Possible values: [Restricted, NotRestricted]

    issuingCarrierCode string

    Two-letter IATA issuing airline code

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

    isPayerTraveling boolean

    Indicates whether the payer is a passenger

    passengersCount integer

    Total number of passengers (excluding infants)

    infantsCount integer

    Number of infants

    payerPassportId string

    Passport identifier of payer

    totalAmounts

    object

    fare number

    Total fare excluding taxes and fees

    taxes number

    Total tax amount

    fee number

    Total fees

    boardingFee number

    Boarding or service fee

    ticketIssueAddress string

    Ticket issuing location

    ancillaryServices

    object[]

  • Array [

    • passenger

    object

    firstName string
    lastName string

    flight

    object

    ticketNumber string

    services

    object[]

  • Array [

    • categoryCode string
    subCategoryCode string
    amount number
    currency string

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

    ticketNumber string

  • ]

  • ]

    • flightLegsDetails

    object[]

    Possible values: <= 4

  • Array [

    • airlineCode stringrequired

    Two-letter IATA airline code

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

    flightNumber stringrequired

    Airline flight number

    Possible values: non-empty

    departureDate date-timerequired

    Local departure airport date/time

    arrivalDate date-timerequired

    Local arrival airport date/time

    departureCountry stringrequired

    ISO-2 country code

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

    departureCity string

    Departure city name

    departureAirport stringrequired

    IATA 3-letter departure airport code

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

    destinationCountry stringrequired

    ISO-2 country code

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

    destinationCity string

    Destination city name

    destinationAirport stringrequired

    IATA 3-letter destination airport code

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

    type LegType (string)required

    Domestic or International

    Possible values: [Domestic, International]

    flightType FlightType (string)

    RoundTrip or OneWay. Required when Risk pre-Auth is enabled

    Possible values: [RoundTrip, OneWay]

    ticketDeliveryMethod string

    For example - P physical or E electronic.

    ticketDeliveryRecipient string

    Ticket recipient name

    fareBasisCode string

    Fare basis or booking code

    serviceClass string

    Cabin or service class

    seatClass string

    Seat or fare class

    stopOverCode StopOverCode (string)required

    O - destination, X - connection, or - blank

    Possible values: non-empty and <= 1 characters, [O, X, ]

    departureTaxAmount number

    Departure tax amount

    departureTaxCurrency string

    ISO-3 currency code

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

    fareAmount number

    Fare amount for this leg

    feeAmount number

    Fees for this leg

    taxAmount number

    Taxes for this leg

    layoutInterval integer

    Minutes between legs

  • ]

    • passengersDetails

    object[]

    Possible values: <= 1

  • Array [

    • passportNumber string

    Passport number exactly as printed

    customerCode string

    Airline customer identifier

    frequentFlyerCode string

    Loyalty program number

    title string

    Passenger title, e.g. Mr, Ms, Dr

    firstName stringrequired

    Passenger first name

    Possible values: non-empty

    lastName stringrequired

    Passenger last name

    Possible values: non-empty

    middleName string

    Required if present on passport

    passengerName string

    Full passenger name as shown on the ticket

    dateOfBirth date

    Date of birth, YYYY-MM-DD

    phone string

    Passenger contact phone number

  • ]

    • level23

    object

    Level 2 / Level 3 transaction data.

    taxIndicator TaxIndicator (string)

    Indicates whether local tax is included.

    • NotIncluded
    • StateOrProvincialIncluded
    • NotSubjectToTax

    Must contain StateOrProvincialIncluded if the local tax field is non-zero.

    Possible values: [NotIncluded, StateOrProvincialIncluded, NotSubjectToTax]

    customerCode string

    Customer / consumer reference identifier.

    Possible values: <= 25 characters

    merchantVatRegistrationNumber string

    Merchant VAT registration number or SBRN.

    Possible values: <= 20 characters

    customerVatRegistrationNumber string

    Customer VAT registration number.

    Possible values: <= 13 characters

    summaryCommodityCode string

    National standard commodity code.

    Possible values: <= 4 characters

    destinationZip string

    Destination postal code.

    Possible values: <= 10 characters

    shipFromZip string

    Shipment origin postal code.

    Possible values: <= 10 characters

    destinationCountryCode string

    Destination country code (ISO-3166).

    Possible values: <= 3 characters

    uniqueVatReference string

    VAT invoice reference number.

    Possible values: <= 15 characters

    orderDate string

    Date order was taken in YYMMDD format.

    Possible values: <= 6 characters, Value must match regular expression ^[0-9]{6}$

    vatOrTaxRate number

    Tax rate applied to freight/shipping (implied decimals).

    lineItemCount integer

    Number of line items. Used as a counter/indicator, not the actual array size.

    lineItemCountTax integer

    Canadian tax line item count.

    taxItems

    object[]

    Up to 6 Canadian tax items per transaction.

    Possible values: <= 6

  • Array [

    • taxAmountIndicator TaxAmountIndicator (string)

    Indicator for additional tax capture / reporting.

    Possible values: [NoAdditionalTaxReporting, AdditionalTaxReporting]

    taxAmount number

    Detailed tax amount (implied decimals).

    taxRate string

    Tax rate applied. Numeric value without decimal point; exponent provided separately. Example: "07500" with taxRateExponent = 3 represents 7.5%.

    Possible values: <= 5 characters

    taxRateExponent integer

    Decimal position for taxRate.

    taxTypeApplied string

    Tax category indicator.

    Possible values: <= 4 characters

    taxTypeIdentifier string

    Type of tax collected.

    Possible values: <= 2 characters

  • ]

    • items

    object[]

    Up to 998 Level 3 line items per transaction.

    Possible values: <= 998

  • Array [

    • commodityCode string

    Commodity classification code.

    Possible values: <= 12 characters

    description string

    Item description.

    Possible values: <= 35 characters

    productCode string

    Product identifier.

    Possible values: <= 12 characters

    quantity string

    Quantity purchased (exponent-based).

    Possible values: <= 12 characters

    unitMeasure string

    Unit of measure code.

    Possible values: <= 12 characters

    price number

    Unit price (implied decimals).

    vatOrTaxAmount number

    VAT or sales tax amount.

    vatOrTaxRate number

    VAT / sales tax rate.

    totalAmount number

    Total line item amount.

    discountRate string

    Discount rate (uses exponent).

    Possible values: <= 5 characters

    discount number

    Discount amount.

    taxType string

    Tax category indicator.

    Possible values: <= 4 characters

    quantityExponentIndicator integer

    Decimal position of quantity.

    discountRateExponent integer

    Decimal position of discountRate.

    discountTreatmentCode DiscountTreatmentCode (string)

    Discount treatment code.

    Possible values: [NoDiscount, PostDiscountTax, PreDiscountTax]

    creditIndicator CreditIndicator (string)

    Debit / Credit indicator for the line item.

    Possible values: [Debit, Credit]

    extendedAmount number

    Quantity x price (net).

  • ]

    • amountDetails

    object

    taxAmount number

    State or provincial tax amount included in the transaction amount. Expressed in the transaction currency, with two implied decimals. May contain zeros.

    nationalTaxAmount number

    National tax amount included in the transaction amount.

    totalDiscount number

    Total discount amount applied.

    totalShipping number

    Freight / shipping amount.

    dutyAmount number

    Duty tax amount.

    vatOrTaxAmount number

    VAT / tax on shipping.

Responses​

OK

Schema

    settleId idType (string)
    Example: 2f00eba7-66ad-4d8b-8d54-b8c9183e664f
    transactionId transactionId (string)

    Nuvei Digital Payments Gateway Transaction ID

    Possible values: <= 20 characters

    externalTransactionId ExternalTransactionId (string)

    The transaction ID of the transaction in the event that an external service is used.

    Possible values: <= 50 characters

    agentId string

    Unique identifier of the AI agent that initiated the transaction on behalf of the end user.

    amount number

    The transaction amount.

    currency string

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

    result

    object

    required

    status stringrequired

    Possible values: [approved, authorizedOnly, declined, error, pending, redirect, challenge, fingerprint, authenticated, authenticationNotSupported, actionRequired]

    errors

    object

    code string

    Possible values: <= 11 characters

    Example: 7000.1000
    reason string

    Possible values: <= 400 characters

    Example: Internal Processing Error
    reference string

    Internal reference for troubleshooting

    Possible values: <= 400 characters

    Example: 110.1290
    authCode string

    The authorization code of the transaction.

    Possible values: <= 128 characters

    providerResponseDetails

    object

    code string

    Possible values: <= 100 characters

    reason string

    Possible values: <= 400 characters

    additionalTransactionInfo

    object

    additionalTransactionBankId string
    additionalExternalTransactionId string
    referenceId string
Loading...