Skip to main content
In-Store Payments

Authorize a payment

Authorizing a payment is the first step of the payment request process. When you submit a payment request, J.P. Morgan sends an authorization request to the issuing bank to obtain approval for the payment. If approved, the second step of the payment request is to capture the funds from the cardholder’s account.

In this guide, learn about the following payment types and features:  

  • Pre-authorizattion
  • Partial authorization support
  • Retrieve authorization details
Note

For Mastercard pre-authorizations or incremental authorizations, ensure that the value of isAmountFinal is set to false. The default value for isAmountFinal is true.

Before you begin

  • Determine your payment use cases including how you need to support capture and if you need to support partial authorizations.
  • Understand the minimum requirements for a simple payment.

Pre-authorization

Pre-authorize funds at the Point of Sale (POS) and obtain approval from issuing bank by using the POST /payments endpoint.

  • Typically used in scenarios where the final amount is not yet known (hospitality, fuel, rentals).
  • Requires card-present indicators (for example, entry mode and device/terminal details) in addition to standard eCommerce fields.
  • The authorization hold must later be followed by a completion/capture or reversal action within network-defined timelines.
    • The authorization expires on the date and time provided in the paymentRequest.authorizations.expirationTimestamp
  • Set captureMethod to MANUAL and isAmountFinal to false for pre-authorization transactions.

The following table shows the minimum required fields for a pre-auth transaction request:

Required fields for pre-auth
Field name Description Comments
currency The currency for the amount fields as a 3-character ISO 4217 currency code.  
amount Total monetary value of the payment including all taxes and fees. Uses implied decimal places according to the ISO 4217 currency code. For example, EUR and GBP use two decimal places, so €10.00 is sent as 1000.
paymentMethodType.card.accountNumber The card or token number.  
captureMethod The value that determines whether the payment is captured immediately, after a delay (default is 120 minutes), or manually with a separate API call. If excluded, the payment is captured immediately. Set to MANUAL for pre-auth.
isAmountFinal

Indicates if the amount provided is final.

  • true - final amount
  • false - amount may change.
  
merchant.merchantSoftware.companyName Company name of software integrated to this API.  
merchant.merchantSoftware.productName The name of the product used for marketing purposes from a consumer's perspective.  
merchant.softMerchant.phone Phone number of the merchant. PayFac required field.
merchant.softMerchant.address.line1 First line of the street address. PayFac required field.
merchant.softMerchant.address.line2 Second line of the address. PayFac required field.
merchant.softMerchant.address.city Name of the municipality. PayFac required field.
merchant.softMerchant.address.postalCode The portion of a party's address that is the encoded representation of a geographic area to facilitate mail delivery services. PayFac required field.
merchant.softMerchant.address.countryCode The country code of the address based on Alpha 3 ISO standards. PayFac required field.
merchant.softMerchant.address.addressTypeCode The classification given to the various addresses captured for a party, such as Doing Business As Address, Legal Entity Address, and Tax Address. PayFac required field.
subMerchantSupplementalData. merchantIdentification.subMerchantId The merchant's account as it appears on the accountholder's statement. PayFac required field.
subMerchantSupplementalData. merchantIdentification.serviceEntitlementNumber The unique number assigned to a merchant by a payment brand to process conveyed transactions. PayFac required field.
subMerchantSupplementalData. merchantIdentification.sellerIdentifier A unique identifier generated by the firm to identify the individual Transaction Division processing, using the American Express (AMEX) OptBlue program under the firm's Service Entitlement (SE) Number. PayFac required field.

HTTP Method: POST
Endpoint: /payments
Scenario: Sending a pre-authorization request

Json
{
  "amount": 2900,
  "captureMethod": "MANUAL",
  "currency": "EUR",
  "initiatorType": "CARDHOLDER",
  "invoiceNumber": "939660",
  "isAmountFinal": false,
  "subMerchantSupplementalData": {
    "merchantIdentification": {
      "subMerchantId": "39016507",
      "sellerIdentifier": "123456"
    }
  },
  "merchant": {
    "merchantSoftware": {
      "companyName": "JPMC",
      "productName": "CP1",
      "softwareId": "027C",
      "version": "20240600.1.6"
    },
    "softMerchant": {
      "name": "softmerchant",
      "address": {
        "countryCode": "FRA",
        "postalCode": "068912",
        "line1": "18 BAYARD AVE",
        "state": "FR",
        "city": "Paris"
      }
    },
    "merchantCategoryCode": "6540"
  },
  "merchantDefined": {
    "merchantDefinedData": "HjBerA1jsrYy3eMZCZhy2H"
  },
  "partialAuthorizationSupport": "NOT_SUPPORTED",
  "paymentMethodType": {
    "card": {
      "accountNumber": "4229989999000012=311220114161752",
      "accountNumberType": "TRACK"
    }
  },
  "pointOfInteraction": {
    "device": {
      "applicationInfo": {
        "deviceType": "IPHONE"
      },
      "attendance": "ATTENDED",
      "capabilities": [
        "EMV_CONTACT"
      ],
      "deviceId": "0001",
      "location": "ON_PREMISE",
      "pinCapability": "PIN_ELIGIBLE",
      "terminalDeviceSerialNumber": "P10_C467D3003",
      "vendorId": "0181"
    },
    "inPerson": {
      "emvInformation": {
        "applicationId": "A0000000031010",
        "emvData": "5F2A020840820220008407A00000000310108A0200008F0192950500000000009A032406179C01009F02060000000002009F03060000000000009F0607A00000000310109F100706010A03A000009F1A0208409F1E0834363744333030339F21031453559F2608E42C02D382E2C07E9F2701809F3303E028C09F34033F00009F3501229F360201549F37041DF5C23D9F3901079F4005F000A0A0019F410200039F6E0420700000",
        "emvSequenceNumber": "0002",
        "panSequenceNumber": "01"
      },
      "entryMethod": "EMV_CONTACT",
      "isCardholderPresent": true,
      "pinProcessing": {
        "pinBlock": null,
        "keySequenceNumber": null
      }
    }
  },
  "retailAddenda": {
    "taxAmount": 100,
    "isTaxable": true,
    "purchaseOrderNumber": "1234567877",
    "orderDate": "2019-09-10"
  },
  "cashBackAmount": null
}

Response:

Json
{
  "transactionId": "a0fd7392-bb9a-440b-96ac-2767dd9d161f",
  "requestId": "491f9f9e-ac41-4b8e-b418-1a8c48419845",
  "transactionState": "AUTHORIZED",
  "responseStatus": "SUCCESS",
  "responseCode": "APPROVED",
  "responseMessage": "Transaction approved by Issuer",
  "paymentMethodType": {
    "card": {
      "accountNumberType": "TRACK",
      "cardType": "VI",
      "cardTypeName": "VISA",
      "maskedAccountNumber": "422998XXXXXX0012",
      "accountUpdater": {
        "hostAccountUpdaterStatusCode": "I"
      },
      "networkResponse": {
        "last4CardNumber": "0000",
        "networkTransactionId": "123456789012345",
        "paymentAccountReference": "13456789012345678923452349237",
        "networkResponseCode": "00"
      },
      "authentication": {
        "authenticationValueResponse": {
          "code": "0"
        }
      },
      "paymentAccountReference": "13456789012345678923452349237"
    }
  },
  "captureMethod": "MANUAL",
  "initiatorType": "CARDHOLDER",
  "accountOnFile": "NOT_STORED",
  "isVoid": false,
  "transactionDate": "2026-07-10T16:10:14.981Z",
  "approvalCode": "208802",
  "hostMessage": "00",
  "isAmountFinal": false,
  "amount": 2900,
  "currency": "EUR",
  "remainingAuthAmount": 2900,
  "merchant": {
    "merchantId": "109151579001",
    "merchantSoftware": {
      "companyName": "JPMC",
      "productName": "CP1",
      "version": "20240600.1.6",
      "softwareId": "027C"
    },
    "merchantCategoryCode": "6540",
    "softMerchant": {
      "name": "softmerchant",
      "address": {
        "line1": "18 BAYARD AVE",
        "city": "Paris",
        "state": "FR",
        "postalCode": "068912",
        "countryCode": "FRA"
      }
    }
  },
  "retailAddenda": {
    "purchaseOrderNumber": "1234567877",
    "orderDate": "2019-09-10",
    "taxAmount": 100,
    "isTaxable": true
  },
  "partialAuthorizationSupport": "NOT_SUPPORTED",
  "partialAuthorization": false,
  "paymentRequest": {
    "paymentRequestId": "a0fd7392-bb9a-440b-96ac-2767dd9d161f",
    "paymentRequestStatus": "PENDING",
    "authorizations": [
      {
        "authorizationId": "a0fd7392-bb9a-440b-96ac-2767dd9d161f",
        "amount": 2900,
        "transactionStatusCode": "AUTHORIZED",
        "authorizationType": "INITIAL",
        "transactionTimestamp": "2026-07-10T16:10:14.981Z",
        "expirationTimestamp": "2031-03-16T00:00:00Z"
      }
    ]
  },
  "invoiceNumber": "939660",
  "subMerchantSupplementalData": {
    "merchantIdentification": {
      "subMerchantId": "39016507",
      "sellerIdentifier": "123456"
    }
  },
  "pointOfInteraction": {
    "device": {
      "capabilities": [
        "EMV_CONTACT"
      ],
      "pinCapability": "PIN_ELIGIBLE",
      "location": "ON_PREMISE",
      "attendance": "ATTENDED",
      "applicationInfo": {
        "deviceType": "IPHONE"
      },
      "vendorId": "0181",
      "terminalDeviceSerialNumber": "P10_C467D3003",
      "deviceId": "0001"
    },
    "inPerson": {
      "isCardholderPresent": true,
      "entryMethod": "EMV_CONTACT",
      "emvInformation": {
        "emvData": "5F2A020840820220008407A00000000310108A0200008F0192950500000000009A032406179C01009F02060000000002009F03060000000000009F0607A00000000310109F100706010A03A000009F1A0208409F1E0834363744333030339F21031453559F2608E42C02D382E2C07E9F2701809F3303E028C09F34033F00009F3501229F360201549F37041DF5C23D9F3901079F4005F000A0A0019F410200039F6E0420700000",
        "applicationId": "A0000000031010",
        "emvSequenceNumber": "0002"
      }
    }
  },
  "merchantDefined": {
    "merchantDefinedData": "HjBerA1jsrYy3eMZCZhy2H"
  },
  "emvKeysVersionNumber": "1773259838"
}

Partial authorization

Partially authorize payments to receive approval for a portion of the original amount when the full amount cannot be approved by using the POST /payments endpoint.

  • Often used in debit or prepaid use cases where available balance is insufficient.
  • Requires additional card-present-specific fields for reconciling multiple tenders against a single purchase.
  • Set partialAuthorizationSupport to SUPPORTED to enable partial authorization.

The following table shows the minimum required fields for this transaction:

Required fields for partial auth
Field name Description Comments
currency The currency for the amount fields as a 3-character ISO 4217 currency code.  
amount Total monetary value of the payment including all taxes and fees. Uses implied decimal places according to the ISO 4217 currency code. For example, EUR and GBP use two decimal places, so €10.00 is sent as 1000.
paymentMethodType.card.accountNumber The card or token number.  
partialAuthorizationSupport Indicates your ability to support a partially approved payment from the issuer. Set to SUPPORTED for partial authorization.
merchant.merchantSoftware.companyName Company name of software integrated to this API.  
merchant.merchantSoftware.productName The name of the product used for marketing purposes from a consumer's perspective.  
merchant.softMerchant.phone Phone number of the merchant. PayFac required field.
merchant.softMerchant.address.line1 First line of the street address. PayFac required field.
merchant.softMerchant.address.line2 Second line of the address. PayFac required field.
merchant.softMerchant.address.city Name of the municipality. PayFac required field.
merchant.softMerchant.address.postalCode The portion of a party's address that is the encoded representation of a geographic area to facilitate mail delivery services. PayFac required field.
merchant.softMerchant.address.countryCode The country code of the address based on Alpha 3 ISO standards. PayFac required field.
merchant.softMerchant.address.addressTypeCode The classification given to the various addresses captured for a party, such as Doing Business As Address, Legal Entity Address, and Tax Address. PayFac required field.
subMerchantSupplementalData. merchantIdentification.subMerchantId The merchant's account as it appears on the accountholder's statement. PayFac required field.
subMerchantSupplementalData. merchantIdentification.serviceEntitlementNumber The unique number assigned to a merchant by a payment brand to process conveyed transactions. PayFac required field.
subMerchantSupplementalData. merchantIdentification.sellerIdentifier A unique identifier generated by the firm to identify the individual Transaction Division processing, using the American Express (AMEX) OptBlue program under the firm's Service Entitlement (SE) Number. PayFac required field.

HTTP Method: POST
Endpoint: /payments
Scenario: Sending a partial authorization request

Json
{
  "amount": 5300,
  "captureMethod": "MANUAL",
  "currency": "EUR",
  "initiatorType": "CARDHOLDER",
  "invoiceNumber": "939660",
  "subMerchantSupplementalData": {
    "merchantIdentification": {
      "subMerchantId": "39016507",
      "sellerIdentifier": "123456"
    }
  },
  "merchant": {
    "merchantSoftware": {
      "companyName": "JPMC",
      "productName": "CP1",
      "softwareId": "027C",
      "version": "20240600.1.6"
    },
    "softMerchant": {
      "name": "softmerchant",
      "address": {
        "countryCode": "FRA",
        "postalCode": "068912",
        "line1": "18 BAYARD AVE",
        "state": "FR",
        "city": "Paris"
      }
    },
    "merchantCategoryCode": "6540"
  },
  "merchantDefined": {
    "merchantDefinedData": "HjBerA1jsrYy3eMZCZhy2H"
  },
  "partialAuthorizationSupport": "SUPPORTED",
  "paymentMethodType": {
    "card": {
      "accountNumber": "4229989999000012=311220114161752",
      "accountNumberType": "TRACK"
    }
  },
  "pointOfInteraction": {
    "device": {
      "applicationInfo": {
        "deviceType": "IPHONE"
      },
      "attendance": "ATTENDED",
      "capabilities": [
        "EMV_CONTACTLESS"
      ],
      "deviceId": "0001",
      "location": "ON_PREMISE",
      "pinCapability": "PIN_ELIGIBLE",
      "terminalDeviceSerialNumber": "P10_C467D3003",
      "vendorId": "0181"
    },
    "inPerson": {
      "emvInformation": {
        "applicationId": "A0000000031010",
        "emvData": "5F2A020840820220008407A00000000310108A0200008F0192950500000000009A032406179C01009F02060000000002009F03060000000000009F0607A00000000310109F100706010A03A000009F1A0208409F1E0834363744333030339F21031453559F2608E42C02D382E2C07E9F2701809F3303E028C09F34033F00009F3501229F360201549F37041DF5C23D9F3901079F4005F000A0A0019F410200039F6E0420700000",
        "emvSequenceNumber": "0002",
        "panSequenceNumber": "01"
      },
      "entryMethod": "EMV_CONTACT",
      "isCardholderPresent": true,
      "pinProcessing": {
        "pinBlock": null,
        "keySequenceNumber": null
      }
    }
  },
  "retailAddenda": {
    "taxAmount": 100,
    "isTaxable": true,
    "purchaseOrderNumber": "1234567877",
    "orderDate": "2019-09-10"
  },
  "cashBackAmount": null
}

Response:

Json
{
  "transactionId": "d6953735-2232-412f-be14-f732cd3cba57",
  "requestId": "6fb5794b-bba4-4b2b-85ee-21dcd20bce6c",
  "transactionState": "AUTHORIZED",
  "responseStatus": "SUCCESS",
  "responseCode": "PARTIAL_APPROVAL",
  "responseMessage": "Transaction partially approved by Issuer",
  "paymentMethodType": {
    "card": {
      "accountNumberType": "TRACK",
      "cardType": "VI",
      "cardTypeName": "VISA",
      "maskedAccountNumber": "422998XXXXXX0012",
      "accountUpdater": {
        "hostAccountUpdaterStatusCode": "I"
      },
      "networkResponse": {
        "last4CardNumber": "0000",
        "networkTransactionId": "123456789012345",
        "paymentAccountReference": "13456789012345678923452349237",
        "networkResponseCode": "10"
      },
      "authentication": {
        "authenticationValueResponse": {
          "code": "0"
        }
      },
      "paymentAccountReference": "13456789012345678923452349237"
    }
  },
  "captureMethod": "MANUAL",
  "initiatorType": "CARDHOLDER",
  "accountOnFile": "NOT_STORED",
  "isVoid": false,
  "transactionDate": "2026-07-13T12:48:00.470Z",
  "approvalCode": "353133",
  "hostMessage": "10",
  "isAmountFinal": true,
  "amount": 1000,
  "currency": "EUR",
  "remainingAuthAmount": 1000,
  "merchant": {
    "merchantId": "109151579001",
    "merchantSoftware": {
      "companyName": "JPMC",
      "productName": "CP1",
      "version": "20240600.1.6",
      "softwareId": "027C"
    },
    "merchantCategoryCode": "6540",
    "softMerchant": {
      "name": "softmerchant",
      "address": {
        "line1": "18 BAYARD AVE",
        "city": "Paris",
        "state": "FR",
        "postalCode": "068912",
        "countryCode": "FRA"
      }
    }
  },
  "retailAddenda": {
    "purchaseOrderNumber": "1234567877",
    "orderDate": "2019-09-10",
    "taxAmount": 100,
    "isTaxable": true
  },
  "partialAuthorizationSupport": "NOT_SUPPORTED",
  "requestedAuthorizationAmount": 5300,
  "partialAuthorization": true,
  "paymentRequest": {
    "paymentRequestId": "d6953735-2232-412f-be14-f732cd3cba57",
    "paymentRequestStatus": "PENDING",
    "authorizations": [
      {
        "authorizationId": "d6953735-2232-412f-be14-f732cd3cba57",
        "amount": 1000,
        "transactionStatusCode": "AUTHORIZED",
        "authorizationType": "INITIAL",
        "transactionTimestamp": "2026-07-13T12:48:00.470Z",
        "expirationTimestamp": "2026-07-20T12:48:00.470Z"
      }
    ]
  },
  "invoiceNumber": "939660",
  "subMerchantSupplementalData": {
    "merchantIdentification": {
      "subMerchantId": "39016507",
      "sellerIdentifier": "123456"
    }
  },
  "pointOfInteraction": {
    "device": {
      "capabilities": [
        "EMV_CONTACTLESS"
      ],
      "pinCapability": "PIN_ELIGIBLE",
      "location": "ON_PREMISE",
      "attendance": "ATTENDED",
      "applicationInfo": {
        "deviceType": "IPHONE"
      },
      "vendorId": "0181",
      "terminalDeviceSerialNumber": "P10_C467D3003",
      "deviceId": "0001"
    },
    "inPerson": {
      "isCardholderPresent": true,
      "entryMethod": "EMV_CONTACT",
      "emvInformation": {
        "emvData": "5F2A020840820220008407A00000000310108A0200008F0192950500000000009A032406179C01009F02060000000002009F03060000000000009F0607A00000000310109F100706010A03A000009F1A0208409F1E0834363744333030339F21031453559F2608E42C02D382E2C07E9F2701809F3303E028C09F34033F00009F3501229F360201549F37041DF5C23D9F3901079F4005F000A0A0019F410200039F6E0420700000",
        "applicationId": "A0000000031010",
        "emvSequenceNumber": "0002"
      }
    }
  },
  "merchantDefined": {
    "merchantDefinedData": "HjBerA1jsrYy3eMZCZhy2H"
  },
  "emvKeysVersionNumber": "1773259838"
}

Retrieve authorization details

After making an authorization request, you can review the authorization details. Complete the following steps to retrieve authorization details:

  1. Send a GET request to the /payments endpoint one of two ways:
    1. Use the requestId returned in the original response as a query parameter.
    2. Use the transactionId returned in the original response as a path parameter.

Payment fields 

Is this page helpful?