Skip to main content

API-only Payment Authorization

POST 
/payment/authorize/

This method allows the merchant to perform a payment transaction by using payment option/authentication details previously obtained, depending on the payment method, in a one-step direct flow.

In the API-only flow, merchants can initiate prepayment transactions directly via API without using the SmartPay widget. This method allows full backend control over the transaction process. When a merchant triggers a prepayment through the API, they provide details such as the transaction amount, currency, customer details, billing address, etc. The API responds with an authorization and a unique reference (transactionReference), which the merchant includes on the buyer's invoice.

The buyer uses this reference (transactionReference) to complete the payment, ensuring that the payment is correctly associated with the transaction. This approach allows merchants to handle the entire payment process backend-only, streamlining operations without needing a frontend integration with the SmartPay widget.

For the API-only Prepayments and Pay Upon Invoice payment methods, the distinction between the two models is made using the type enumeration parameter, please refer below.

Name                             Description                           Type                             
paymentOptionDetails of the payment.Object
  - invoicePaymentDetails of the invoice.Object
    - - typeEither prepayment - PREPMNT,
or Pay Upon Invoice - PAYINVC.		String
info

This endpoint uses the SmartPay BaseURL and Authorization.

Request​

Header Parameters

    Content-Type stringrequired

    Must be application/json

    Accept-Language stringrequired

    Must be be en-US

    Origin stringrequired

    The origin of the request

    User-Agent stringrequired

    The client making the request

    Authorization stringrequired

    Basic M2lwN2Yx...OGU3Mg==

Body

required

    paymentOption

    object

    required

    The type of payment method and its details

    oneOf

    Either a Pre-Payment or Payment Upon Invoice.

    type string

    Possible values: [PREPMNT, PAYINVC]

    Code of the specific payment option selected. Pre-Payment (PREPMNT) or Pay Upon Invoice (PAYINVC).

    partnerReference stringnullable

    Possible values: <= 64 characters, Value must match regular expression ^[a-zA-Z0-9\-_\.:]+$

    Transaction identifier provided by the merchant. If provided must be unique (for that merchant)

    paymentSplit

    object

    nullable

    If passed, defines all related information for split payments. Not supported on Hosted Payment Page

    paymentSplitDestinations

    object[]

    required

    Possible values: >= 1

  • Array [

    • destinationReference stringrequired

    Possible values: <= 127 characters

    Destination merchant account alias

    amount decimalrequired

    Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

    Transaction modification amount

    currencyCode stringrequired

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

    Transaction modification currency. The 3-letter currency ISO-4217 code

    description stringrequired

    Possible values: <= 127 characters

    A terse description of the good or service being sold i.e., the reason for the payment

  • ]

    • shippingAddress

    object

    nullable

    addressLine1 stringrequired

    Possible values: <= 60 characters

    Street name.

    addressLine2 string

    Possible values: <= 60 characters

    Apartment, suite, unit, building, floor or other secondary address information.

    addressLine3 string

    Possible values: <= 60 characters

    Specific delivery instructions, department names, or additional floor information.

    city stringrequired

    Possible values: <= 50 characters

    The city or localitly of the address.

    countryCode stringrequired

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

    ISO-3 code of the address country (e.g., DEU for Germany).

    number string

    Possible values: <= 10 characters

    The house or building number corresponding to the street address.

    postCode stringrequired

    Possible values: <= 10 characters

    The postal or ZIP code of the address.

    state string

    Possible values: <= 3 characters

    3-letter code of the address state. Mandatory when countryCode corresponds to Canada or USA.

    targetMerchantAccountReference stringnullable

    Possible values: <= 127 characters

    Indicates the account number to be used instead of the main merchant account number of the channel.

    billingAddress

    object

    required

    Consumer's billing address data. See Address in Data model.

    addressLine1 stringrequired

    Possible values: <= 60 characters

    Street name.

    addressLine2 string

    Possible values: <= 60 characters

    Apartment, suite, unit, building, floor or other secondary address information.

    addressLine3 string

    Possible values: <= 60 characters

    Specific delivery instructions, department names, or additional floor information.

    city stringrequired

    Possible values: <= 50 characters

    The city or localitly of the address.

    countryCode stringrequired

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

    ISO-3 code of the address country (e.g., DEU for Germany).

    number string

    Possible values: <= 10 characters

    The house or building number corresponding to the street address.

    postCode stringrequired

    Possible values: <= 10 characters

    The postal or ZIP code of the address.

    state string

    Possible values: <= 3 characters

    3-letter code of the address state. Mandatory when countryCode corresponds to Canada or USA.

    businessConsumer

    object

    nullable

    Company data, in case the consumer is a business or a legal entity.
    Mandatory, unless consumer is provided.
    consumer and businessConsumer objects may not be submitted together.

    companyName stringrequired

    Possible values: <= 100 characters

    Name of the legal entity

    companyRegistrationCountryCode string

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

    Company registration country ISO2 or ISO3 code

    companyRegistrationNumber string

    Possible values: <= 50 characters

    Company registration number

    companyType stringrequired

    Possible values: <= 100 characters

    culture string

    Possible values: <= 5 characters

    Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g., en-de). This field is not case sensitive.

    emailAddress stringrequired

    Possible values: <= 255 characters

    Customer email address for any notification

    taxId string

    Possible values: <= 30 characters

    Person's tax identification number

    consumer

    object

    nullable

    Consumer's personal data, in case the consumer is a physical person.
    Mandatory, unless businessConsumer is provided.
    consumer and businessConsumer objects may not be submitted together.

    culture string

    Possible values: <= 5 characters

    Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g., en-de). This field is not case sensitive.

    dateOfBirth date

    Possible values: <= 10 characters, Value must match regular expression ^\d{4}-\d{2}-\d{2}$

    Date of birth. Format - YYYY-MM-DD. Mandatory for payment option registration flow. Minimum date allowed is 1900-01-01

    emailAddress emailrequired

    Possible values: <= 255 characters

    Customer email address for any notification

    firstName stringrequired

    Possible values: <= 60 characters

    Person first name

    gender string

    Possible values: <= 6 characters

    Person gender

    homePhone string

    Possible values: <= 30 characters

    Person's home phone number (including the country code)

    lastName stringrequired

    Possible values: <= 60 characters

    Person last name

    merchantCustomerId string

    Possible values: <= 255 characters

    Consumer/Customer Account Id in the merchant system. When provided into the Create Checkout API, SmartPay will request e-wallet account creation which will have external account reference equals to the given merchantCustomerId value.

    middleName string

    Possible values: <= 60 characters

    The customer's middle name

    mobilePhone string

    Possible values: <= 30 characters

    Person's mobile phone number (including the country code)

    taxId string

    Possible values: <= 30 characters

    Person's tax identification number

    timezone string

    Possible values: <= 50 characters

    Preferred timezone name

    title string

    Possible values: <= 3 characters

    Person title

    workPhone string

    Possible values: <= 30 characters

    Person's work phone number (including the country code)

    criteria

    object[]

    nullable

    List of custom key-value pairs that the merchant can submit.
    The names callBackUrl and redirectUrl will be disregarded.
    For transactions using Apple Pay or Google Pay™, please consult the respective integration pages for details on required domain configuration and button styling parameters within this object.

  • Array [

    • name stringrequired

    Possible values: <= 50 characters

    name of the parameter. The value must be unique within the criteria array

    value stringrequired

    Possible values: <= 100 characters

    value of the parameter

  • ]

    • customReferences

    object

    nullable

    For external party usage. Please refer to Data Model for more details.

    custom1 string

    Possible values: <= 255 characters

    generic custom reference

    custom2 string

    Possible values: <= 255 characters

    generic custom reference

    custom3 string

    Possible values: <= 255 characters

    generic custom reference

    customerAccountId stringnullable

    Possible values: <= 255 characters

    Consumer's account identifier in the merchant's system. To be used as an external account reference. Disregarded when provided as a path parameter.

    extraInfo

    object

    nullable

    Payment extra information to define the product group, to display different set of payment options (Card, SEPA, PayPal...) for different products.

    customerGroup string

    Possible values: <= 100 characters

    In case customer group rule is defined in channel configuration, this value is used for channel evaluation

    productGroup string

    Possible values: <= 100 characters

    In case customer group rule is defined in channel configuration, this value is used for channel evaluation

    payment

    object

    required

    The payment amount to be charged against the payment option.

    amount decimalrequired

    Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

    Transaction modification amount

    currencyCode stringrequired

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

    Transaction modification currency. The 3-letter currency ISO-4217 code

    description stringrequired

    Possible values: <= 127 characters

    A terse description of the good or service being sold i.e., the reason for the payment

    shopCountry stringnullable

    Possible values: <= 2 characters

    The ISO 3166-1 alpha-2 code of the shop country. Must match at least one of the countries configured for the merchant.

Responses​

Payment authorization successfully created

Schema

    reconciliationReferenceId stringrequired

    External payment provider unique transaction identifier.
    Within SmartPay, each order on your side is represented by one checkout transactionID. You may use this transactionID to perform the initial checkout, retrieve an overall status or for later modifications, like manual capture or refunds.
    On the payment side, this may lead to multiple financial transactions, e.g., one payment transaction about the captured amount (which will be settled to your account), and later a refund transaction (which will be debited from your account / deducted from your payout).
    The reconciliationReferenceId has been introduced to allow you to keep track of those financial transactions, as it represents the financial transactionID, as you would see it in the payment provider's merchant portal (e.g., our Merchant Panel) or settlement files.

    description stringrequired

    Transaction description, as specified by you in the checkout API request.

    paymentStatus stringrequired

    Possible values: [CREATED, CAPTURED, AUTHORIZATION_PENDING, AUTHORIZATION_COMPLETED, FAILED, CAPTURE_PENDING, CANCELLATION_PENDING, EXPIRED, CANCELLED, SETTLED, CHARGEBACK]

    Current payment status of the initial transaction. Please refer here for more information.

    creationDate stringrequired

    Transaction creation date and time.

    lastStatusDate stringrequired

    Transaction status changing date and time

    partnerReference string

    Transaction identifier provided by the merchant

    transactionOverview

    object

    required

    transactionId stringrequired

    Possible values: <= 36 characters

    The unique identifier of the transaction generated on transaction creation.

    acquirerResponse string

    paymentProviderResponse sent in the Complete Autorize response in case of error.

    amount decimalrequired

    Possible values: Value must match regular expression ^\d{1,18}\.\d{2}$

    Transaction modification amount

    currencyCode stringrequired

    Transaction modification currency. The 3-letter currency ISO-4217 code.

    customReferences

    object

    For external party usage. Please refer to Data Model for more details.

    custom1 string

    Possible values: <= 255 characters

    generic custom reference

    custom2 string

    Possible values: <= 255 characters

    generic custom reference

    custom3 string

    Possible values: <= 255 characters

    generic custom reference

    customerAccountId string

    Unique customer identifier

    deal

    object

    Details of the deal. Used only for 3RI payments (Partial or split shipment and Delayed shipment use cases).

    amount decimal

    Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

    The total amount of the deal. The sum of all payments with the same dealReference may not exceed this amount. Used only for Split Shipment flow.

    dealReference string

    Possible values: <= 21 characters

    Deal identifier.

    typeCode string

    Possible values: <= 6 characters, [3RIPSS, 3RIDS]

    Deal type

    mit boolean

    Flag to show if created transaction relates to merchant-initiated transactions.

    paymentMethod string

    Used payment option code. Please refer to the Data Model for more information.
    Payment option CARDS is returned by SmartPay in case the actual card brand has not been selected by the consumer yet or if it could not be determined.

    paymentOrigin string

    Possible values: [HOSTED_PAYMENT_PAGE, PAYMENT_AUTHORIZE_S2S, CHECKOUT, SUBSCRIPTION_MIT, MERCHANT_MIT]

    Displays the origin flag marked upon creation of the transaction.

    targetMerchantAccountReference string

    If provided, the payment is processed in favour of the indicated submerchant account, and the main merchant account number is ignored.

    transactionReference string

    External payment provider reference of the Pre-Payment or Payment Upon Invoice. To be sent each time there is a value present in the data source.

    modification

    object

    required

    Array of all performed transaction modifications.

    creationDate date-time

    Date and time of the modification processing start.

    error

    errorBadRequestExternal

    error string

    Possible values: [gateway_processing, payment_provider_processing]

    indicates at which level of processing the error appeared

    errorDetails

    object

    context object

    Additional error details, as received from the third party

    gatewayDescription string

    Possible values: <= 400 characters

    Error message returned by payment gateway

    paymentProviderDescription string

    Possible values: <= 400 characters

    Error message returned by payment provider

    lastStatusDate date-time

    Date and time of the modification processing completion.

    modificationAmount

    object

    The payment amount to be charged against the payment option.

    amount decimalrequired

    Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

    Transaction modification amount

    currencyCode stringrequired

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

    Transaction modification currency. The 3-letter currency ISO-4217 code

    description stringrequired

    Possible values: <= 127 characters

    A terse description of the good or service being sold i.e., the reason for the payment

    modificationData

    object

    Additional details of the modification

    cancelId uuid

    SmartPay internal unique identifier for cancel request.

    captureId uuid

    SmartPay internal unique identifier for capture request.

    customReferences

    object

    For external party usage. Please refer to Data Model for more details.

    custom1 string

    Possible values: <= 255 characters

    generic custom reference

    custom2 string

    Possible values: <= 255 characters

    generic custom reference

    custom3 string

    Possible values: <= 255 characters

    generic custom reference

    modificationId stringrequired

    For external party usage.

    paymentSplitResults

    object[]

    Defines destinations for which the payment was split and their results.

  • Array [

    • destinationReference string

    Destination merchant account alias

    error string

    In case of a failed Debit Account or Refund request, contains error description in the following format [ {'responseCode'} ] {responseDescription}.

    splitUniqueReference stringrequired

    Unique reference of the split transaction received in response of Debit Account or Refund.

    status stringrequired

    Possible values: <= 127 characters

    Mapped to responseCode received from Debit Account or Refund. If the code returns 0000, it is a SUCCESS, otherwise it's ERROR.

  • ]

    • programRefundErrorMessage string

    Message in case of error during KC Program refund.

    programRefundId string

    Stores the refund reference in case the merchant to program refund was successful.

    programRefundStatus string

    Reflects the status of the refund from merchant to program level in SmartPay - success/error.

    reconciliationReferenceId string

    External provider unique transaction identifier - unique reference for capture or cancel and refund unique reference for refund.

    refundId uuid

    SmartPay internal unique identifier for refund request.

    type stringrequired

    Possible values: [CAPTURE, CANCELATION, CHARGEBACK, SETTLEMENT, REFUND]

    Type of the performed transaction modification.

    status string

    Actualized transaction or refund status after the performed modification.

    statusHistory

    object[]

  • Array [

    • error string

    Text message explaining the error issue

    modificationAmount

    object

    required

    option string

    SmartPay code of the payment option used.

    storedPaymentOptionReference string

    stored payment option reference

    amount decimalrequired

    Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

    Transaction modification amount

    currencyCode stringrequired

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

    Transaction modification currency. The 3-letter currency ISO-4217 code

    description stringrequired

    Possible values: <= 127 characters

    A terse description of the good or service being sold i.e., the reason for the payment

    status string

    Status of the transaction modification or initial payment transaction.

    statusDate date-timerequired

    Modification transaction status changing date and time.

  • ]

Loading...
 Imprint
|
Data protection and privacy
© 2025 J.P. Morgan Mobility Payments Systems GmbH. All rights reserved.