Skip to main content

Orbital

Overview​

Gateway Website: https://www.jpmorgan.com/merchant-services/solutions/payment-gateway
Developer Documentation: https://developer.jpmorgan.com/products/orbital-api
Default Currency: Currency determined by Orbital Merchant ID

Request Objects: BillingAddress, ShippingAddress, CreditCard, Check, OrderInfo,SoftDescriptors, StoredCredentials, ThreeDSecure

Gateway Endpoints
This implementation of Chase's Orbital gateway forwards requests to the below endpoints.
Production: https://orbital1.chasepaymentech.com
Sandbox: https://orbitalvar1.chasepaymentech.com

Supported Request Parameters​

* denotes a required field ** denotes a required field for certain card brands
Field NameTypeOrbital MappingNotes
gatewaystringn/aOrbital
username*stringorbitalConnectionUsername (header)Orbital Connection Username set up on Orbital Gateway. Not case-sensitive
password*stringorbitalConnectionPassword (header)Orbital Connection Password used in conjunction with Orbital Username. Case-sensitive
merchantId*stringmerchantID (header)Gateway merchant account number assigned by Merchant Services. 6 digits in length
versionstringversionFeature Release version in "x.x" format
merchantBin*stringmerchant.​binTransaction routing definition assigned by merchant services. Currently only "000001" for Stratus is supported
terminalId*stringmerchant.​terminalIdMerchant Terminal ID assigned by Orbital Merchant Services
amount*integerorder.​amountTransaction amount in whole units. Implied decimal, including those currencies that are a zero exponent. For example, both $100.00 (an exponent of 2) and ¥100 (an exponent of 0) should be sent as amount=10000.
orderInfo.​orderIdstringorder.​IdMerchant-Defined Order Number. Field defined and supplied by the auth originator and echoed back in response. The first 8 characters should be unique for each transaction.
orderInfo.​industryTypestringindustryTypeIndustry Type of the Transaction.

Valid values:
EC- e-commerce transaction
IN- Installment
IV- IVR (PINless Debit Bill Pay Only)
MO- Mail Order transaction
RC- Recurring Payment
creditCard.​expYearintegerpaymentInstrument.​card.​ccExpThe four-digit expiration year of the card. Example: 2022
creditCard.​expMonthintegerpaymentInstrument.​card.​ccExpThe expiration month of the card. Max 2 digits. Example: 3
creditCard.​numberstringpaymentInstrument.​ccAccountNumCard number or TokenEx token - TokenEx will replace the token with the detokenized number
creditCard.​cvvstringcardholderVerification.​ccCardVerifyNumThe three- or four-digit number on the back of a credit card (on the front for American Express).

This field is required if the merchant would like to use the Card Code Verification (CCV) security feature.

Cardholder information must be stored securely and in accordance with the Payment Card Industry (PCI) Data Security Standard.
creditCard.Brand**stringpaymentInstrument.​card.​cardBrandOnly Applicable to International Maestro. This field is sent to Orbital to ensure the card is processed as Maestro
check.​accountNumberstringpaymentInstrument.​ecp.​ecpCheckDDAThe customer's account number or TokenEx token - TokenEx will replace the token with the detokenized value
check.​routingNumberstringpaymentInstrument.​ecp.​ecpCheckRTThe bank's routing number.
check.​redepositFrequencyintegerpaymentInstrument.​ecp.​ecpReDepositFreqApplicable only to merchants processing standard, extended, or advanced verification Electronic check transactions. See the Orbital documentation for valid values.
check.​redepositIndicatorstringpaymentInstrument.​ecp.​ecpReDepositIndApplicable only to merchants processing standard, extended, or advanced verification Electronic check transactions. See the Orbital documentation for valid values.
check.​sameDayIndicatorstringpaymentInstrument.​ecp.​ecpSameDayIndApplicable only to merchants processing standard, extended, or advanced verification Electronic check transactions.

Valid Values:
Y- Same Day ACH requested
N- Next Day ACH requested
Leave blank for no change to the ACH processing
check.​imageReferenceNumberstringpaymentInstrument.​ecp.​ecpImageReferenceNumberImage reference number associated with a check.
check.​terminalCitystringpaymentInstrument.​ecp.​ecpTerminalCityThis value corresponds to the city of the point of sale the check is processed at.
check.​terminalStatestringpaymentInstrument.​ecp.​ecpTerminalStateThis value corresponds to the city of the point of sale the check is processed at.
check.​actionCodeenumpaymentInstrument.​ecp.​ecpActionCodeThis element is required to extend the transType for additional ECP processing methods.

Valid values:
0- Blank
1- Validate Only
2- Validate and Prenote (Debit, supported for GBP European Direct Debit (EUDD) processing)
3- Validate and Verify (Credit)
4- Advanced Verification: Validate/ASV
5- Advanced Verification: Validate/ASV and AOA
6- Advanced Verification: Validate/ASV/Deposit
7- Advanced Verification: Validate/ASV and AOA / Deposit
8- Advanced Verification: Validate/ASV / Refund
9- Advanced Verification: Validate/ASV and AOA / Refund
10- Advanced Verification: Validate/ASV / Pre-Note
11- Advanced Verification: Validate/ASV and AOA / Pre-Note
check.​authorizationMethodenumpaymentInstrument.​ecp.​ecpAuthMethodCode used to identify the method used by customers to authorize debits to their accounts.

Valid values:
0- (blank value, default)
1- written
2- internet
3- telephone
4- accounts receivable
5- point of purchase
check.​accountTypeenumpaymentInstrument.​ecp.​ecpBankAcctTypeThe type of bank account. Certain bank account types require you to use certain ACH transaction types.
Valid values:
1- Checking
2- Savings
4- CorporateChecking
check.​deliveryMethodenumpaymentInstrument.​ecp.​ecpDelvMethodRequired for Electronic Check processing.

This field indicates the preferred manner to deposit the transaction.

Valid values:
1- Best possible method
2- ACH
billingAddress.​address1stringavsBilling.​avsAddress1Cardholder billing address line 1. Mandatory for PINless Debit e-commerce transactions
billingAddress.​address2stringavsBilling.​avsAddress2Cardholder billing address line 2.
billingAddress.​statestringavsBilling.​avsStateCardholder billing state.
billingAddress.​citystringavsBilling.​avsCityCardholder billing city.
billingAddress.​zipstringavsBilling.​avsZipCardholder billing postal code.
billingAddress.​countrystringavsBilling.​avsCountryCodeCardholder billing country code in Alpha-3 ISO format
billingAddress.​phonestringavsBilling.​avsPhoneCardholder billing phone number.​m
billingAddress.​phoneTypestringavsBilling.​avsPhoneTypeCustomer's telephone type.

Valid values:
D - Day
H - Home
N - Night
W - Work
tax.​Exemptboollevel2.​taxIndTrue = tax exempt transaction
False = tax applies to this transaction
tax.​Amountintegerlevel2.​taxAmountAmount of sales tax assessed to the transaction. Required for Level 2 Data.

Implied two decimal, including those currencies that are a zero exponent.
tax.​totalTaxAmountstringlevel2.​pCardTotalTaxAmountLocal Tax (PST or QST) on the invoice.
tax.​nationalTaxRatestringlevel2.​pCardNationalTaxRateNational Tax Rate (HST or GST). Required for MasterCard L2 transactions. Three decimals implied.

For example: An interest rate of 6.25% should be sent as "06250".
tax.​nationalTaxstringlevel2.​pCardNationalTaxNational tax rate. Required for Visa Canada L2 transactions. Implied two decimals.
tax.​localTaxRatestringlevel2.​pCardLocalTaxRateLocal tax rate. Required for Visa interchange. Three decimals implied.
tax.​localTaxAmountstringlevel2.​pCardLocalTaxAmountLocal Tax (PST or QST) on the invoice.
tax.​pstTaxRegistrationNumberstringlevel2.​pCardPstTaxRegNumberCanadian provincial sales tax registration number.
tax.​customerVatRegistrationNumberstringlevel2.​pCardCustomerVatRegNumberCustomer Tax Registration Number. Visa only.
tax.​merchantVatRegistrationNumberstringlevel2.​pCardMerchantVatRegNumberMerchant VAT registration ID. Required for Visa and Mastercard Level 2 transactions.
orderInfo.​PurchaseOrderNumberstringlevel2.​pCardOrderIDPurchase order or other number used by the merchant’s customer to track the order.

Required for Level 2 Data.

Do not include the following characters: < > ? ; ’ : ” [ ] \ | ` = ~ ! @ # % ^ & * ( ) _ +
orderInfo.​requestorNamestringlevel2.​pCardRequestorNameName of the consumer that ordered or purchased the product or service if not the card member.
orderInfo.​commodityCodestringlevel2.​pCardCommodityCodeCommodity Code used to categorize purchases for VAT reporting.

Valid values:
LID = Line Item Detail
SUMM = Summary Tax
orderInfo.​shippingAddress.​address1stringlevel2.​pCardDestAddressCardholder shipping address line 1.
orderInfo.​shippingAddress.​address2stringlevel2.​pCardDestAddress2Cardholder shipping address line 2.
orderInfo.​shippingAddress.​citystringlevel2.​pCardDestCityCardholder shipping city.
orderInfo.​shippingAddress.​statestringlevel2.​pCardDestStateCdCardholder shipping state.
orderInfo.​shippingAddress.​zipstringlevel2.​pCardDestZipCardholder shipping postal code.
orderInfo.​shippingAddress.​firstNamestringlevel2.​cardDestNameCardholder shipping name.
orderInfo.​shippingAddress.​lastNamestringlevel2.​cardDestNameCardholder shipping name.
creditCard.​amexTranAdvAddn1stringlevel2.​amexTranAdvAddn1The TAA Record is used to further identify the purchase associated with the charge to the cardholder.

It is also used in Purchasing/Procurement card transactions to provide specific details about the transaction to the cardholder for tracking purposes.

TAAs should be as concise as possible, while still providing adequate information. For example, a TAA of Merchandise would not be acceptable.
creditCard.​amexTranAdvAddn2stringlevel2.​amexTranAdvAddn2See creditCard.amexTranAdvAddn1 above.
creditCard.​amexTranAdvAddn3stringlevel2.​amexTranAdvAddn3See creditCard.amexTranAdvAddn1 above.
creditCard.​amexTranAdvAddn4stringlevel2.​amexTranAdvAddn4See creditCard.amexTranAdvAddn1 above.
tokenExTransactionCodestringFor Force Capture
order.​PriorAuthCd

For Card Purchase/Capture/Refund/Void Requests
order.​TxRefNum		For Force Capture:
This field is being used to capture the prior approval code obtained manually in case of Force Capture request.

For Card Purchase/Capture/Refund Requests:
This field is being used to map the Transaction Reference Number received during authorization or purchase, and is provided in the response as tokenExTransactionCode.

Note: Refunds processed after four months will require credit card details to be submitted in the refund request.
threeDSecure.​CAVVstringVisa:
cryptogram.​verifyByVisaCAVV

MasterCard:
cryptogram.​mcSecureCodeAAV

Discover:
cryptogram.​digitalTokenCryptogram

AmericanExpress:
cryptogram.​digitalTokenCryptogram		Cardholder authentication verification value (CAVV).

Note:- CAVV is mapped to cryptogram.digitalTokenCryptogram, If the credit card brand is other than Visa, MasterCard, Discover or AmericanExpress.
threeDSecure.​ECIstringadditionalAuthInfo.​authenticationECIIndRaw electronic commerce indicator (ECI)

Valid values are
2, 5, 6, 7 and 20.

For more information please visit Orbital API docs here
threeDSecure.​Xidstringcryptogram.​verifyByVisaXIDTransaction identifier.
Note: Only available for Card brand VISA.
threeDSecure.​DigitalTokenCryptogramstringcryptogram.​digitalTokenCryptogramFor Customer Digital Payment Tokens, this is the unique transaction cryptogram generated by the digital wallet provider. It should be submitted as it was received.

This field is being ignored and set to CAVV value in case of card brands Discover, MasterCard, and American Express.
threeDSecure.​PaymentBrandProgramCodestringadditionalAuthInfo.​pymtBrandProgramCodePayment Brand Program Code

Valid values:

MUP=Mastercard Utility Payment Program (MUPP)
DPB=Discover ProtectBuy
ASK=American Express Safekey

Note: Value for this parameter is set by TokenEx in case, if the card brand Discover and Amex as "DPB" and "ASK" respectively.
threeDSecure.​UseStoredAAVIndstringcryptogram.​useStoredAAVIndUse Stored AAV Indicator

This element is required on recurring payments for International Maestro.

Valid values:

Y=Submit the Static AAV stored by Gateway with this transaction.

This should not be submitted if the AAV element is populated.
paymentActionInd**stringadditionalAuthInfo.​paymentActionInd**Note: If paymentActionInd is not sent, the value will be set to "F" by default.

Used by Mastercard and International Maestro to clearly distinguish a pre-authorization from a final authorization. Refer to Mastercard Pre- and Final Authorizations.

Valid Values:

P=Pre-Authorization
F=Final Authorization
storedCredentials.​Initiatorstringimpacts merchantInitiatedTransaction.​mitMsgTypeValid values:
"cardholder", "merchant".
This field is used in the inference of an Orbital mitMsgType. See table below.
storedCredentials.​CredentialStoredboolmerchantInitiatedTransaction.​mitStoredCredentialIndSee usage in The Basics - Stored Credentials.
True = "Y"
False = "N"

This field is used in the inference of an Orbital mitMsgType. See table below.
storedCredentials.​PreviousNetworkTransactionIdstringmerchantInitiatedTransaction.​mitSubmittedTransactionIDSee usage in The Basics - Stored Credentials. Obtained from Orbital response field order.mitReceivedTransactionID.
storedCredentials.​TransactionTypestringmerchantInitiatedTransaction.​mitMsgTypeValid values:
"recurring", "installment", "unscheduled", or any specific mitMsgType. This field is used for the inference of an Orbital mitMsgType. See table below.
softDescriptors.​MerchantNamestring(25)softDesc.​softDescMercNameThe Merchant Name field should be what is most recognizable to the cardholder (Company name or trade name). The actual length of this field is tied to Host and the Size of the Description field used. Required for Soft Descriptors.

For card actions, there are three options which affect the MerchantName:
- Max 3 bytes
- Max 7 bytes
- Max 12 bytes

Check actions:
- Required for Check Processing transactions
- Max 15 bytes
softDescriptors.​Descriptionstring(18)softDesc.​softDescProdDescProvides an accurate description of the product(s).

For card actions:
- If MerchantName=3 bytes, then Max=18 bytes
- If MerchantName=7 bytes, then Max=14 bytes
- If MerchantName=12 bytes, then Max=9 bytes

Check actions:
- 10 bytes Max

Required for Soft Descriptors.
softDescriptors.​MerchantUrlstring(13)softDesc.​softDescMercURLBase URL of the Merchant's website.

Only one of the Phone, URL, or E-mail fields should be sent; all others should be null-filled.
softDescriptors.​ContactInfostringsoftMerchantDescriptors.​smdContactInfoMerchant Contact Information

If this element begins with a number, it is considered a phone number; otherwise, it is a URL or an email address.

Valid phone formats:
- NNN-NNN-NNNN
- NNN-AAAAAAA
- NNN-NNNNNNN

Valid URL formats:
- Must contain “.”

Valid Email formats:
- Must contain “@”

(Non-e-Commerce) transactions with URL do not qualify for best interchange.
softDescriptors.​MerchantIdstringsoftMerchantDescriptors.​smdMerchantIDMerchant Location ID

Mastercard strongly recommends this field be populated and limit Max Char to 15.
softDescriptors.​MerchantDBAstringsoftMerchantDescriptors.​smdDBAMerchant “Doing Business As” name

Format:
- Aggregator Name*Account Name
softDescriptors.​MerchantCategoryCodestring(4)softMerchantDescriptors.​smdMCCMerchant MCC

Merchant category code used for the authorization.
softDescriptors.​EstablishmentNumberstringsoftMerchantDescriptors.​smdServiceEstablishmentNumService Establishment Number (SE#)

Soft merchant information SE# assigned by the Payment Facilitator and passed to Merchant Services in the transaction. If the value is not populated, it will be defaulted at transaction division level.
softDescriptors.​TaxExemptCharityIndicatorstringsoftMerchantDescriptors.​smdTaxExemptCharityInd501(c)(3) Tax Exempt Charity Indicator

Soft merchant information field that identifies if a merchant is 501(c)(3) Tax Exempt Charity eligible.

Valid values:
- Y = Merchant is 501(c)(3) eligible
- N = Merchant is not 501(c)(3) eligible
- null or “ “ = Blank

This field is sent to Stratus during settlement when the following MCC codes (smdMCC) are used in authorization:
- MCC = 8661 (Religious Organization)- MCC = 8398 (Charity)

For any other MCC codes, this flag is ignored.
softDescriptors.​MerchantAddress.​Address1stringsoftMerchantDescriptors.​smdStreetMerchant Street

Merchant street address 1 where transaction took place.

Concatenated with Address2 as below:
Address1 - Address2
softDescriptors.​MerchantAddress.​Address2stringsoftMerchantDescriptors.​smdStreetMerchant Street

Merchant street address 2 where transaction took place.

Concatenated with Address1 as below:
Address1 - Address2
softDescriptors.​MerchantAddress.​CitystringsoftDesc.​softDescMercCityMerchant City

Merchant city where transaction took place.
softDescriptors.​MerchantAddress.​StatestringsoftMerchantDescriptors.​smdRegionMerchant Region

Merchant state/province where transaction took place.

For US states, must be a valid value else transaction will decline.
softDescriptors.​MerchantAddress.​ZipstringsoftMerchantDescriptors.​smdPostalCodeMerchant Postal Code

Merchant zip/postal code where transaction took place.
softDescriptors.​MerchantAddress.​Countrystring(3)softMerchantDescriptors.​smdCountryCodeMerchant Country Code

Merchant numeric ISO country code where transaction took place.
softDescriptors.​MerchantAddress.​Phonestring(13)softDesc.​softDescMercPhoneMerchant Phone Number

Valid Formats:
- ###-###-####
- ###-#######

Only one of the Phone, URL, or E-mail fields should be sent; all others should be null-filled.
softDescriptors.​MerchantAddress.​Emailstring(19)softDesc.​softDescMercEmailMerchant Email Address

Only one of the Phone, URL, or E-mail fields should be sent; all others should be null-filled.
Force Capture

Card Force Capture: This transaction type captures an Authorized transaction using a prior approval code that was obtained manually or over the phone with the customer’s bank.

Check Force Capture: A Force Capture request includes an e-Check transaction in the next settlement cycle without validating it at the time of the request.

Note: User must include tx-passthrough = true for Force Capture requests.

Stored Credential TransactionType to Orbital mitMsgType Inference Table​

The table below shows how different value combinations impact the forwarded mitMsgType field. If the below inferences do not work for your business case, send the preferred mitMsgType in the StoredCredentials.TransactionType and it will be forwarded unmodified.
The following message types can be inferred: CSTO, CREC, CINS, CUSE, MUSE, MREC, MINS.
The following mitMsgTypes are unable to be inferred and should be explicitly sent: CGEN, CEST, SKIP, MRSB, MRAU, MINC, MNOS, and MDEL.

InitiatorCredentialStoredTransactionTypeForwarded mitMsgType
CardholderTruenullCUSE
CardholderFalsenullCSTO
CardholderTrueunscheduledCUSE
CardholderFalseunscheduledCSTO
CardholderTruerecurringCREC
CardholderFalserecurringCREC
CardholderTrueinstallmentCINS
CardholderFalseinstallmentCINS
MerchantTruenullMUSE
MerchantTrueunscheduledMUSE
MerchantTruerecurringMREC
MerchantTrueinstallmentMINS

Example Requests​

{
  "merchantBin": "000001",
  "creditCard": {
    "brand": "Visa",
    "number": "4111111111111111",
    "expMonth": 2,
    "expYear": 2024,
    "cvv": "123"
  },
  "orderInfo": {
    "orderId": "12534",
    "industryType": "EC"
  },
  "storedCredentials": {
    "initiator": "merchant",
    "credentialStored": true,
    "previousNetworkTransactionId": "012227692162172",
    "transactionType": "installment"
  },
  "amount": 1200,
  "gateway": "Orbital",
  "username": "<Your Orbital username>",
  "password": "<Your Orbital password>",
  "merchantId": "<Your Orbital merchant ID>",
  "terminalId": "001"
}

Gateway Response Parameters​

Field NameTypeOrbital Result MappingNotes
approvedboolean[see notes]True in the following case:
-order.status.procStatus = "0" and...
-order.status.approvalStatus- = "1" OR order.status.procStatusMessage = "Approved"
approvalCodestringorder.status.authorizationCodeUnique transactional-level code issued by the bank or service establishment for approvals. PINless Debit transactions could return blanks or N/A.
providerTransactionCodestringorder.txRefNumA unique value is assigned by the Gateway for each transaction.
tokenExTransactionCodestringorder.txRefNumBase64 encoded Orbital gateway response field order.txRefNum
NetworkTransactionIdstringorder.mitReceivedTransactionId
order.receivedNetworkTransactionId		The transaction id returned by the brand.
orderReceivedNetworkTransactionId for Discover cards.
MerchantReferenceIdstringorder.orderIDValue sent in request's OrderInfo.OrderId parameter
CustomerProfileIdstringprofile.customerRefNumReference value that is associated with the customer at the time of the transaction.
VerificationResult.CvvRawstringcardholderVerification.hostCvvRespCodeThe CVV (card verification value) response returned by issuer.
VerificationResult.AvsRawstringavsBilling.hostAVSRespCodeThe address verification service (AVS) response returned by issuer.
VerificationResult.ProviderParsed.CvvMatchstringcardholderVerification.cvvRespCodeCVV match as parsed by Orbital
VerificationResult.ProviderParsed.AvsstringavsBilling.avsRespCodeAVS values as parsed by Orbital

Example Responses​

{
  "gatewayResponse": {
    "rawResponse": "{\"transType\":\"A\",\"merchant\":{\"bin\":\"000001\",\"merchantID\":\"445138\",\"terminalID\":\"001\"},\"paymentInstrument\":{\"card\":{\"cardBrand\":\"VI\"},\"eudd\":{}},\"order\":{\"orderID\":\"2007\",\"txRefNum\":\"65722F3F062E3DAA0000044600000923415653C0\",\"txRefIdx\":\"0\",\"respDateTime\":\"20231207154655\",\"status\":{\"procStatus\":\"0\",\"procStatusMessage\":\"Approved\",\"hostRespCode\":\"100\",\"respCode\":\"00\",\"approvalStatus\":\"1\",\"authorizationCode\":\"tst933\",\"pymtBrandAuthResponseCode\":\"00\",\"pymtBrandResponseCodeCategory\":\"A\"}},\"emvInfo\":{},\"avsBilling\":{\"avsRespCode\":\"3 \",\"hostAVSRespCode\":\"  \"},\"cardholderVerification\":{\"cvvRespCode\":\"M\",\"hostCVVRespCode\":\"M\"},\"debit\":{},\"cardTypeIndicator\":{},\"earlyWarningSystem\":{},\"foreignExchange\":{},\"realTimeAccountUpdater\":{},\"giftcard\":{},\"profile\":{},\"managedBilling\":{}}",
    "gatewayErrors": [],
    "tokenExTransactionCode": "NjU3MjJGM0YwNjJFM0RBQTAwMDAwNDQ2MDAwMDA5MjM0MTU2NTNDMA==",
    "approvalCode": "tst933",
    "providerTransactionCode": "65722F3F062E3DAA0000044600000923415653C0",
    "approved": true,
    "verificationResult": {
      "avsRaw": "  ",
      "cvvRaw": "M",
      "providerParsed": {
        "cvvMatch": "M",
        "avs": "3 "
      }
    },
    "merchantReferenceId": "2007"
  },
  "referenceNumber": "2312071446547660830",
  "success": true,
  "error": "",
  "message": "",
  "thirdPartyStatusCode": "200"
}
Last updated on