Payment Service ¶

The payment service provides endpoints which allows a user to recharge or auto-recharge their account using a credit card. Also, the user can save/retrieve a credit card for future use.

Topics

Payment Service

Endpoints ¶

Recharge a Stored Value Card with a Credit Card ¶

POST payment/recharge.json¶

Adds stored value to a user’s card by paying with a credit card (or saved credit card). Note: User’s email address must be verified in order to perform a recharge.

The following authentication methods are allowed for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID in which to perform the operation in.
printedCardNumber (String) – (required) The card of the user.
amount (Decimal) – (required) The amount to charge/deduct.
paymentMethod (Object) – (required) See PaymentMethod (PaymentService) for format of the object.
address (Object) – (required if paymentMethod is CC) See Address for format of the object.
metadata (Map[String->String]) – (optional) Mapping of custom request data to be sent to the credit card processor. Possible keys include device_data.

"result": "success"

Indicates that the operation succeeded.

JSON Parameters:
	result (String) – (required) `success` chargeResponse (Object) – (required) See `ChargeResponse` for format of the object

Example:

{
    "result": "success",
    "chargeResponse": {
        "amount"                   : "25.00",
        "cardType"                 : "VISA",
        "expDate"                  : "01/2067",
        "lastFour"                 : "1111",
        "processorAuthCode"        : "010101",
        "processorReferenceNumber" : "1234567ABCDE",
        "processorResponseCode"    : 0,
        "processorResponseMessage" : "Approved",
        "transactionDatetime"      : "2013-08-20 18:14:25 -0400",
        "transactionState"         : "Succeeded"
    }
}

"result": "invalidInputs"

Indicates that the operation was not performed because the inputs could not be validated.

JSON Parameters:

result (String) – (required) invalidInputs
errorCode (String) – (required) The error code of the failure
errorMessage (String) – (required) The human readable error message of the failure
errorsByField (Object) – (required) Object representing a map of a slash (/) separated path to the field in question and a list of field validation error codes. In the case where the cardSecurityCode within the top-level paymentMethod field wasn’t long enough, you would get something like "paymentMethod/cardSecurityCode": ["too_short"] }

Example:

{
    "result": "invalidInputs",
    "errorCode": "enrollment_input.validation_error",
    "errorMessage": "Validation error for input fields",
    "errorsByField": {
        "paymentMethod/expirationMonth": ["too_low"],
        "paymentMethod/saveCard": ["cannot_auto_recharge_without_saving_card"],
        "paymentMethod/cardholderName": ["too_long"],
        "address/street": ["null_field"]
    }
}

Field input error codes are:

Error code	Definition
`too_low`	Numeric value is below the minimum acceptable value (e.g. an expiration month of 0 was sent)
`too_high`	Numeric value is above the maximum acceptable value (e.g. an expiration month of 13 was sent)
`null_field`	A null or empty value was sent where an empty string is not allowed
`too_short`	The value sent was shorter than the minimum number of characters
`too_long`	The value sent was longer than the maximum number of characters
`invalid_non_integral`	The value sent was not an integer value
`invalid_date`	Date format is invalid or specified date is not a valid input (e.g. the current year is 2013 and an expirationYear value of 2012 was sent)
`cannot_auto_recharge_without_saving_card`	Client requested auto recharge, but specified that credit card should not be saved. This is not possible, because a saved credit card is required in order to automatically recharge the card at a later date

"result": "failure"

Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary).

JSON Parameters:

result (String) – (required) failure
errorCode (String) – (required) The error code of the failure
errorMessage (String) – (required) The (human readable) error message of the failure
errorDetail (String) – (required. Deprecated as of version 20.38) Additional detail provided by the system in the case when CC auth or capture steps fail or when the PXS is unable to add SV to the card. Should not be shown to the end user, however this may be useful for diagnostic purposes. Replaced by object in errorDetails list below with errorCode recharge.cc_auth_declined.detail as of version 20.38
errorDetails (List[Object]) – (optional) Additional details provided by the system in the case when CC auth or capture steps fail or when the PXS is unable to add SV to the card if available. See CreditCardDeclineDetail for format of the objects.

Example 1:

{
    "result": "failure",
    "errorCode": "recharge.amount_below_minimum",
    "errorMessage": "Recharge amount is below allowed minimum for this card"
}

Example 2:

{
    "result": "failure",
    "errorCode": "recharge.cc_auth_declined",
    "errorMessage": "Credit card authorization was declined",
    "errorDetails": [
      {
        "errorCode": "recharge.cc_auth_declined.avs",
        "errorMessage": "Postal code matches, but street address not verified."
      },
      {
        "errorCode": "recharge.cc_auth_declined.cvv",
        "errorMessage": "CV match failed"
      },
      {
        "errorCode": "recharge.cc_auth_declined.detail",
        "errorMessage": "Transaction declined - gateway rejected"
      }
    ]
}

Enable Automatic Recharge for a Stored Value Card ¶

POST payment/autoRechargeEnable.json¶

Establishes an automatic recharge of the card when the stored value balance is at or below the configured threshold.

Note

User’s email address must be verified in order to perform a recharge. NOTE: The card is charged immediately to confirm that the card is valid for future recharges.

The following authentication methods are allowed for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) The card of the user.
amount (Decimal) – (required) The amount to charge/deduct.
threshold (Decimal) – (optional) Threshold at which auto recharge is configured. The merchant default is used if not specified. Only used if merchant program is configured to be set on a per-account basis.
paymentMethod (Object) – (required) See PaymentMethod (PaymentService) for format of the object.
address (Object) – (required if paymentMethod is CC) See Address for format of the object.
metadata (Map[String->String]]) – (optional) Mapping of custom request data to be sent to the credit card processor. Possible keys include device_data.

"result": "success"

Indicates that the operation succeeded.

JSON Parameters:
	result (String) – (required) `success` chargeResponse (Object) – (required) Present if result=success. See `ChargeResponse` for format of the object

Example:

{
    "result": "success",
    "chargeResponse": {
        "amount"                   : "25.00",
        "cardType"                 : "VISA",
        "expDate"                  : "01/2067",
        "lastFour"                 : "1111",
        "processorAuthCode"        : "010101",
        "processorReferenceNumber" : "1234567ABCDE",
        "processorResponseCode"    : 0,
        "processorResponseMessage" : "Approved",
        "transactionDatetime"      : "2013-08-20 18:14:25 -0400",
        "transactionState"         : "Succeeded"
    }
}

"result": "invalidInputs"

Indicates that the operation was not performed because the inputs could not be validated.

JSON Parameters:

result (String) – (required) invalidInputs
errorCode (String) – (required) The error code of the failure
errorMessage (String) – (required) The (human readable) error message of the failure
errorsByField (Object) – (required) Object representing a map of a slash (/) separated path to the field in question -> list of field validation error codes, e.g. in the case where the “cardSecurityCode” within the top-level “paymentMethod” field wasn’t long enough, you would get something like "paymentMethod/cardSecurityCode": ["too_short"] }

Example:

{
    "result": "invalidInputs",
    "errorCode": "enrollment_input.validation_error",
    "errorMessage": "Validation error for input fields",
    "errorsByField": {
        "paymentMethod/expirationMonth": ["too_low"],
        "paymentMethod/saveCard": ["cannot_auto_recharge_without_saving_card"],
        "paymentMethod/cardholderName": ["too_long"],
        "address/street": ["null_field"]
    }
}

Field input error codes are:

Error code	Definition
`too_low`	Numeric value is below allowed range of values (e.g. an expiration month of 0 was sent)
`too_high`	Numeric value is above allowed range of values (e.g. an expiration month of 13 was sent)
`null_field`	A null or empty value was sent where an empty string is not allowed
`too_short`	The value sent was shorter than the allowed minimum number of characters
`too_long`	The value sent was longer than the allowed maximum number of characters
`invalid_non_integral`	The value sent was not a integer value
`invalid_date`	Date format is invalid or specified date is not a valid input (e.g. the current year is 2013 and an expirationYear value of 2012 was sent)
`cannot_auto_recharge_without_saving_card`	Client requested auto recharge, but specified that credit card should not be saved. This is not possible, because a saved credit card is required in order to automatically recharge the card at a later date

"result": "failure"

Indicates that the operation did not complete successfully, and was rolled back as best as able (if necessary).

JSON Parameters:

result (String) – (required) failure
errorCode (String) – (required) The error code of the failure
errorMessage (String) – (required) The (human readable) error message of the failure
errorDetail (String) – (required. Deprecated as of version 20.38) Additional detail provided by the system in the case when CC auth or capture steps fail or when the PXS is unable to add SV to the card. Should not be shown to the end user, however this may be useful for diagnostic purposes. Replaced by object in errorDetails list below with errorCode recharge.cc_auth_declined.detail as of version 20.38
errorDetails (List[Object]) – (optional) Additional details provided by the system in the case when CC auth or capture steps fail or when the PXS is unable to add SV to the card if available. See CreditCardDeclineDetail for format of the objects.

Example 1:

{
    "result": "failure",
    "errorCode": "recharge.amount_below_minimum",
    "errorMessage": "Recharge amount is below allowed minimum for this card"
}

Example 2:

{
    "result": "failure",
    "errorCode": "recharge.cc_auth_declined",
    "errorMessage": "Credit card authorization was declined",
    "errorDetails": [
      {
        "errorCode": "recharge.cc_auth_declined.avs",
        "errorMessage": "Postal code matches, but street address not verified."
      },
      {
        "errorCode": "recharge.cc_auth_declined.cvv",
        "errorMessage": "CV match failed"
      },
      {
        "errorCode": "recharge.cc_auth_declined.detail",
        "errorMessage": "Transaction declined - gateway rejected"
      }
    ]
}

Disable Auto Recharge for a Stored Value Card ¶

POST payment/autoRechargeDisable.json¶

Disables auto recharge functionality for a given account

The following authentication methods are allowed for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The user’s printed (loyalty) card number deleteSavedCard (Boolean) – (optional) If true, saved credit card is also deleted. Default: `true`

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Delete Saved Credit Card Attached to Stored Value Card ¶

DELETE payment/savedCreditCard.json¶

Deletes saved credit card information for a given account

Note

The user must not be enrolled in Auto Recharge, else this will fail. In such a case, use autoRechargeDisable with deleteSavedCard set to true

The following authentication methods are allowed for this endpoint:

Query Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) The user’s printed (loyalty) card number
lastFour (String) – (required) Last four digits of the credit card to be deleted
savedCardCode (String) – (required) Saved card code for the credit card to be deleted, as gotten from the GET payment/savedCard.json resource

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Get Payment Configuration ¶

GET payment/paymentConfig.json¶

Returns various configuration values for Auto-Recharge and valid Credit Card Types.

The following authentication methods are allowed for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. cardTemplateCode (Integer) – (required) Paytronix-assigned program code.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` config (Object) – (required) See `PaymentConfig` for format of the object.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Get Saved Credit Card Information ¶

GET payment/savedCard.json¶

Returns a saved card (if any) which can be used in other transactions.

The following authentication methods are allowed for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` savedCard (Object) – (required) See `SavedCreditCardResponsePaymentMethod` for format of the object.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Check Card Auto Recharge Status ¶

GET payment/autoRechargeStatus.json¶

Identifies if a user is enrolled in auto recharge.

The following authentication methods are allowed for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user.

"result": "success"

JSON Parameters:

enrolled (Boolean) – (required) true if the user is enrolled in auto recharge. Otherwise false.
amount (Decimal) – (required) The user’s configured recharge amount.
threshold (Decimal) – (required) The user’s configured threshold amount.
savedCard (Object) – (required) The user’s saved card information. See SavedCreditCardResponsePaymentMethod for format of the object.
savedPaymentMethod (Object) – (optional) The user’s saved payment method information. See ResponsePaymentMethod for format of the object.

Get Recharge History ¶

GET payment/rechargeHistory.json¶

Returns cardholder’s recharge history, if they have ever recharged their card

The following authentication methods are allowed for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` history (List[Object]) – (required) See `ChargeHistoryResponse` for format of the object.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Enable Auto Recharge Threshold Monitoring ¶

POST payment/enableAutoRechargeMonitoring.json¶

Enable the card’s stored value balance to be monitored against the configured threshold. If the stored value balance falls at or below the threshold, the card is flag as auto recharge qualified and will be present in the response of a call to endpoint GET payment/pendingAutoRecharges.json

Note

This pending card will NOT be processed by Paytronix’s regular Auto Recharge engine for credit card recharge

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) The card of the user.
amount (Decimal) – (required) The amount to charge/deduct.
threshold (Decimal) – (optional) Threshold at which auto recharge is configured. The merchant default is used if not specified. Only used if merchant program is configured to be set on a per-account basis.

"result": "success"

Indicates that the operation succeeded.

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

Indicates that the operation did not complete successfully.

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure errorMessage (String) – (required) The (human readable) error message of the failure

Disable Auto Recharge Threshold Monitoring ¶

POST payment/disableAutoRechargeMonitoring.json¶

Disable auto recharge monitoring for the given card.

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user.

"result": "success"

Indicates that the operation succeeded.

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

Indicates that the operation did not complete successfully.

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure errorMessage (String) – (required) The (human readable) error message of the failure

Get Pending Monitored Auto Recharge Events ¶

GET payment/pendingAutoRecharges.json¶

When Auto Recharge is in Monitoring Only mode, returns up to 100 cards whose SV balance have fallen below specified threshold during the past 7 days

The following authentication methods are allowed for this endpoint:

B2B authentication

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.

"result": "success"

Indicates that the operation succeeded.

JSON Parameters:
	result (String) – (required) `success` recharges (List[Object]) – (required) See `PendingAutoRechargesResponse` for format of the object.

"result": "failure"

Indicates that the operation did not complete successfully.

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure errorMessage (String) – (required) The (human readable) error message of the failure

Add Payment Method ¶

POST payment/addPaymentMethod.json¶

Add and save specified payment method and link it to the given card

The following authentication methods are allowed for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
ccProcessorId (Integer) – (optional) Id of the CcProcessor to use when adding Spreedly payment tokens.
printedCardNumber (String) – (required) The user’s printed (loyalty) card number
paymentMethod (Object) – (required) Only UnencryptedCreditCardPaymentMethod and SpreedlyTokenPaymentMethod are valid. See PaymentMethod (PaymentService) for format of the object.
defaultUsages (List[String]) – (required) Uses for card, can include "AUTO_RECHARGE", "MOBILE_PAYMENT_DEFAULT", "INSTANT_PAYMENT", or "SUBSCRIPTION"
nickname (String) – (optional) Nickname for payment method.
metadata (Map[String->String]) – (optional) Mapping of custom request data to be sent to the credit card processor. Possible keys include device_data.

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Edit Payment Method Usages ¶

POST payment/editPaymentMethodUsages.json¶

Update default usages of specified payment method

The following authentication methods are allowed for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) The user’s printed (loyalty) card number
paymentMethod (Object) – (required) Only SpreedlyTokenPaymentMethod and SavedSpreedlyTokenPaymentMethod are valid. See PaymentMethod (PaymentService) for format of the object.
defaultUsages (List[String]) – (required) Uses for card, can include "AUTO_RECHARGE", "MOBILE_PAYMENT_DEFAULT", "INSTANT_PAYMENT", or "SUBSCRIPTION"

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Delete Payment Method ¶

DELETE payment/deletePaymentMethod.json¶

Delete specified payment method

The following authentication methods are allowed for this endpoint:

Query Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) The user’s printed (loyalty) card number
paymentMethod (Object) – (required) Only SavedCreditCardPaymentMethod, SpreedlyTokenPaymentMethod, and SavedSpreedlyTokenPaymentMethod are valid. See PaymentMethod (PaymentService) for format of the object.

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Get Saved Payment Method ¶

GET payment/savedPaymentMethod.json¶

Get default payment method for a specified usage of given card if exists

The following authentication methods are allowed for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The user’s printed (loyalty) card number usage (String) – (required) One of `"AUTO_RECHARGE"`, `"MOBILE_PAYMENT_DEFAULT"`, `"INSTANT_PAYMENT"`, or `"SUBSCRIPTION"`

"result": "success"

JSON Parameters:
	result (String) – (required) `success` paymentMethod (Object) – (required) See `ResponsePaymentMethod` for format of the object.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Get Saved Payment Methods ¶

GET payment/savedPaymentMethods.json¶

Get all saved payment methods for given card if exists

The following authentication methods are allowed for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The user’s printed (loyalty) card number

"result": "success"

JSON Parameters:
	result (String) – (required) `success` paymentMethods (List[Object]) – (required) See `ResponsePaymentMethod` for format of the object.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Create Checkout Session ¶

POST payment/createCheckoutSession.json¶

Creates a Checkout Session for the Stripe Hosted Payment Page.

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
ccProcessorId (Integer) – (required) Credit Card Processor ID associated with the Web Sale Program.
cancelUrl (String) – (required) Url for the guest to redirected to from the Stripe Hosted page if the payment is cancelled.
successUrl (String) – (required) Url for the guest to redirected to from the Stripe Hosted page if the payment succeeds.
lineItems (LineItem) – (required) See LineItem for format of the object.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` checkoutSession (CheckoutSession) – (required) See `CheckoutSession` for format of the object.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Get Payment Intent ¶

GET payment/paymentIntent.json¶

Get the Payment Intent associated with a stripe checkout session.

The following authentication methods are allowed for this endpoint:

B2B authentication

Query Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
ccProcessorId (Integer) – (required) Credit Card Processor ID associated with the Web Sale Program.
paymentIntentId (String) – (required) The payment intent ID associated with a stripe checkout session.
checkoutSessionId (String) – (optional) The checkout session ID associated with a stripe checkout session.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` paymentIntent (PaymentIntent) – (required) See `PaymentIntent` for format of the object.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Capture Payment Intent ¶

POST payment/capturePaymentIntent.json¶

Capture the Payment Intent associated with a stripe checkout session.

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. ccProcessorId (Integer) – (required) Credit Card Processor ID associated with the Web Sale Program. paymentIntentId (String) – (required) The payment intent ID associated with a stripe checkout session.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` paymentIntent (PaymentIntent) – (required) See `PaymentIntent` for format of the object.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Cancel Payment Intent ¶

POST payment/cancelPaymentIntent.json¶

Cancel the Payment Intent associated with a stripe checkout session.

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. ccProcessorId (Integer) – (required) Credit Card Processor ID associated with the Web Sale Program. paymentIntentId (String) – (required) The payment intent ID associated with a stripe checkout session.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` paymentIntent (PaymentIntent) – (required) See `PaymentIntent` for format of the object.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Validate Merchant For Apple Pay ¶

POST payment/validateApplePayMerchant.json¶

Validate a merchant to complete the Merchant Validation for an Apple Pay session.

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. validationUrl (String) – (required) The validation URL Apple provides as part of the event in onValidateMerchant. domainName (String) – (required) The Apple verified domain name for Apple Pay for the merchant.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` session (ApplePayMerchantSession) – (required) See `ApplePayMerchantSession` for format of the object.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Register Merchant Domain for Apple Pay ¶

POST payment/registerApplePayDomain.json¶

Register a merchant’s domain with Apple to allow Apple Pay support for that domain.

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. domainName (String) – (required) The domain name to register for Apple Pay for the merchant.

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Unregister Merchant Domain for Apple Pay ¶

POST payment/unregisterApplePayDomain.json¶

Unregister a merchant’s domain with Apple to disallow Apple Pay support for that domain.

The following authentication methods are allowed for this endpoint:

B2B authentication

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. domainName (String) – (required) The domain name to deregister for Apple Pay for the merchant. reason (String) – (required) Human readable reason for unregistering the domain

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Get Apple Pay Merchant Details ¶

GET payment/applePayMerchantDetails.json¶

Get the merchant details for Apple Pay stored in Apple.

The following authentication methods are allowed for this endpoint:

B2B authentication

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` details (ApplePayMerchantDetails) – (required) See `ApplePayMerchantDetails` for format of the object.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Reply Objects ¶

Credit Card Type Values ¶

AMEX: American Express
DINERS_CLUB: Diners Club
DISCOVER: Discover
JCB: JCB
MASTERCARD: MasterCard
VISA: Visa
ALELO: Alelo
CABAL: Cabal
CARNET: Carnet
DANKORT: Dankort
ELO: Elo
MAESTRO: Maestro
NARANJA: Naranja
SODEXO: Sodexo
VR: Vr

PaymentConfig¶

JSON Parameters:

autoRechargeEnabled (Boolean) – (required) True if the user can enroll in the Auto-Recharge feature.
autoRechargeThreshold (Decimal) – (required) If the Stored Value balance is at or below this threshold, then the system will perform an Auto-Recharge.
rechargeMinAmount (Decimal) – (required) This is the minimum amount a user can specify for how much is charged when performing a Recharge or Auto-Recharge.
rechargeMaxAmount (Decimal) – (required) This is the maximum amount a user can specify for how much is charged when performing a Recharge or Auto-Recharge.
cardTypes (List[Object]) – (optional) See CardTypeEntry for format of the objects.
oneTimeRechargeEnabled (Boolean) – (optional) Is One Time Recharge enabled
isThresholdPerAccount (Boolean) – (optional) Is there an Auto Recharge threshold per account
ccProcessorType (Map[String->String]) – (required) Mapping of program and CC processor type for the given merchant. Possible keys include autoRecharge, egift, webCardSales, loyaltyCardSales, subscriptions, and mobilePayment. Values are one of PAYFLOW or SPREEDLY.

Address¶

Note

Please refer to Supported Country Codes and Supported Country State/Province Codes under the Glossary for a list of appropriate values for the corresponding Address fields.

JSON Parameters:

street (string) – (required) Credit card billing street address
city (string) – (required) Credit card billing city
stateProvince (string) – (required) Two-letter code representing credit card billing state/province
postalCode (string) – (required) Credit card owner’s zip/postal code
country (string) – (required) Credit card owner’s country, one of: US or CA

CardTypeEntry¶

JSON Parameters:
	code (String) – (required) See Credit Card Type Values label (String) – (required) The name of the type.

PaymentMethod (PaymentService)¶: Can be one of the methods below

Note

Only CreditCardPaymentMethod, SavedCreditCardPaymentMethod, SavedSpreedlyTokenPaymentMethod, and SpreedlyTokenPaymentMethod are allowed when using the POST payment/recharge.json or POST payment/autoRechargeEnable.json endpoints

CreditCardPaymentMethod¶

JSON Parameters:

paymentMethodType (String) – (required) CC
cardType (String) – (required) Paytronix-assigned code. See Credit Card Type Values
cardholderName (String) – (required) The name on the credit card.
cardNumber (String) – (required) The credit card number (no spaces or punctuation).
expirationMonth (Integer) – (required) The month of the expiration (1 = Jan, …, 12 = Dec).
expirationYear (Integer) – (required) The year of the expiration (4 digits like: 2019)
cardSecurityCode (String) – (required) Also known as the CVV, CVV2, CVVC, or CSC code on the back of the credit card.
saveCard (Boolean) – (required) Save this credit card for future use as the default credit card for this account. Default: false

SavedCreditCardPaymentMethod¶

JSON Parameters:
	paymentMethodType (String) – (required) `SAVED_CC` savedCardCode (String) – (required) This code was returned by the Payment Service endpoint `savedCard`. lastFour (String) – (required) The last four digits of the full `cardNumber`. This was returned by the Payment Service endpoint `savedCard`.

SavedSpreedlyTokenPaymentMethod¶

JSON Parameters:
	paymentMethodType (String) – (required) `SAVED_SPREEDLY_TOKEN` tokenLastFour (String) – (required) Last four digits of the Spreedly token savedCardCode (String) – (required) This code was returned by the Payment Service endpoint `savedPaymentMethod` or `savedPaymentMethods`

SpreedlyTokenPaymentMethod¶

JSON Parameters:

paymentMethodType (String) – (required) SPREEDLY_TOKEN
token (String) – (required) Paytronix-assigned code. See Credit Card Type Values
nickname (String) – (required) Nickname of payment method
tokenType (String) – (optional) One of "credit_card", "apple_pay", "android_pay", or "google_pay"
saveCard (Boolean) – (optional) Whether this payment method is saved for future use as the default payment method for this account. Default: false

StoredValuePaymentMethod¶

JSON Parameters:
	paymentMethodType (String) – (required) `SV`

PointsPaymentMethod¶

JSON Parameters:
	paymentMethodType (String) – (required) `POINTS`

UnencryptedCreditCardPaymentMethod¶

JSON Parameters:

paymentMethodType (String) – (required) CC
cardType (String) – (required) Paytronix-assigned code. See Credit Card Type Values
cardholderName (String) – (required) The name on the credit card.
cardNumber (String) – (required) The credit card number (no spaces or punctuation).
expirationMonth (Integer) – (required) The month of the expiration (1 = Jan, …, 12 = Dec).
expirationYear (Integer) – (required) The year of the expiration (4 digits like: 2019)
cardSecurityCode (String) – (required) Also known as the CVV, CVV2, CVVC, or CSC code on the back of the credit card.
saveCard (Boolean) – (optional) Save this credit card for future use as the default credit card for this account. Default: false
address (Object) – (optional) Address associated with payment method. See Address for format of the object.

ResponsePaymentMethod¶: Can be one of the methods below

SavedCreditCardResponsePaymentMethod¶

JSON Parameters:

type (String) – (required) SAVED_CC
cardType (String) – (required) Paytronix-assigned code. See Credit Card Type Values
cardholderName (String) – (required) The name on the credit card.
lastFour (String) – (required) Last four digits of full cardNumber. For display to the user (instead of the entire cardNumber). Must be passed along with savedCardCode when paymentMethod is SAVED_CC
expirationMonth (Integer) – (optional) The month of the expiration (1 = Jan, …, 12 = Dec).
expirationYear (Integer) – (optional) The year of the expiration (4 digits like: 2019)
savedCardCode (String) – (required) Must be passed along with lastFour when paymentMethod is SAVED_CC
isAutoRechargeDefault (Boolean) – (required) Is Auto Recharge a default usage of this payment method
isPayByMobileDefault (Boolean) – (required) Is Pay By Mobile a default usage of this payment method
nickname (String) – (optional) Nickname of payment method
address (Object) – (optional) Address associated with payment method. See Address for format of the object.

SavedSpreedlyTokenResponsePaymentMethod¶

JSON Parameters:

type (String) – (required) SAVED_SPREEDLY_TOKEN
tokenLastFour (String) – (required) Last four digits of the Spreedly token. Used to construct a SAVED_SPEEDLY_TOKEN payment method to call various endpoints
cardType (String) – (optional) Paytronix-assigned code of the underlying credit card type. See Credit Card Type Values
cardholderName (String) – (optional) The name on the credit card.
lastFour (String) – (optional) Last four digits of full cardNumber. For display to the user (instead of the entire cardNumber).
expirationMonth (Integer) – (optional) The month of the expiration (1 = Jan, …, 12 = Dec).
expirationYear (Integer) – (optional) The year of the expiration (4 digits like: 2019)
savedCardCode (String) – (required) Must be passed along with tokenLastFour when construct a SAVED_SPREEDLY_TOKEN payment method when calling various endpoints
nickname (String) – (optional) Nickname of payment method
address (Object) – (optional) Address associated with payment method. See Address for format of the object.
paymentTokenType (String) – (optional) One of "credit_card", "apple_pay", "android_pay", or "google_pay"
defaultUsages (List[String]) – (required) Uses for card, can include "AUTO_RECHARGE", "MOBILE_PAYMENT_DEFAULT", "INSTANT_PAYMENT", or "SUBSCRIPTION". This will be an empty array if the token is not the default payment method for any usage

ChargeResponse¶

JSON Parameters:

transactionDatetime (String) – (required) Date at which the transaction occurred, in the format yyyy-MM-dd HH:mm:ss Z, ex: 2012-05-23 16:29:22 -0400
transactionState (String) – (required) Resulting transaction state, one of: Succeeded, Failed
processorResponseCode (Integer) – (required) The Credit Card processor specific response code
processorResponseMessage (String) – (required) The Credit Card processor specific response message
processorReferenceNumber (String) – (required) The Credit Card processor specific reference number for tracking this transaction
authCode (String) – (required) The authorization code returned by the Credit Card processor
amount (Decimal) – (required) The recharge amount requested
paymentMethodType (String) – (required) One of "CC", "ENCRYPTED_CC", "SAVED_CC", "SPREEDLY_TOKEN", "SV", or "POINTS"
paymentMethodNickname (String) – (optional) Nickname for payment method
cardType (String) – (optional) Paytronix-assigned code. See Credit Card Type Values
lastFour (String) – (optional) The last four digits of the card number
expDate (String) – (optional) The expiration date of the card (format is MM/yyyy)
disableCc (Boolean) – (optional) Is CC disabled
billingState (Integer) – (optional) The billing state or province code
billingZip (String) – (optional) The billing postal code

ChargeHistoryResponse¶

JSON Parameters:

transactionDatetime (String) – (required) Date at which the transaction occurred, in the format yyyy-MM-dd HH:mm:ss Z, ex: 2012-05-23 16:29:22 -0400
transactionState (String) – (required) Resulting transaction state, one of: Succeeded, Failed
processorResponseCode (Integer) – (required) The Credit Card processor specific response code
processorResponseMessage (String) – (required) The Credit Card processor specific response message
processorReferenceNumber (String) – (required) The Credit Card processor specific reference number for tracking this transaction
authCode (String) – (required) The authorization code returned by the Credit Card processor
amount (Decimal) – (required) The recharge amount requested
cardType (String) – (required) Paytronix-assigned code. See Credit Card Type Values
lastFour (String) – (required) The last four digits of the card number
expDate (String) – (required) The expiration date of the card (format is MM/yyyy)

PendingAutoRechargesResponse¶

JSON Parameters:

printedCardNumber (String) – (required) Primary card number of the account
amount (Decimal) – (required) Recharge amount specified by guest
storedValueBalance (Decimal) – (required) Current balance of Stored Value wallet
threshold (Decimal) – (required) Effective Auto Recharge Stored Value wallet threshold for this account
savedCard (Object) – (optional) The user’s saved card information. See ResponsePaymentMethod for format of the object.

AutoRechargeStatusResponse¶

JSON Parameters:

enrolled (Boolean) – (required) Primary card number of the account
amount (Decimal) – (optional) Recharge amount specified by guest
threshold (Decimal) – (optional) Effective Auto Recharge Stored Value wallet threshold for this account
savedCard (Object) – (optional) The user’s saved card information. See SavedCreditCardResponsePaymentMethod for format of the object.
savedPaymentMethod (Object) – (optional) The user’s saved payment method information. See ResponsePaymentMethod for format of the object.

CreditCardTokenDetails¶

JSON Parameters:

cardType (String) – (required) Paytronix-assigned code. See Credit Card Type Values
cardholderName (String) – (required) The name on the credit card.
lastFour (String) – (required) Last four digits of full cardNumber. For display to the user (instead of the entire cardNumber).
expirationMonth (Integer) – (required) The month of the expiration (1 = Jan, …, 12 = Dec).
expirationYear (Integer) – (required) The year of the expiration (4 digits like: 2019)

CreditCardDeclineDetail¶

JSON Parameters:
	errorCode (String) – (required) Paytronix-assigned error code. Possible values include `recharge.cc_auth_declined.avs`, `recharge.cc_auth_declined.cvv`, and `recharge.cc_auth_declined.detail`. errorMessage (String) – (required) The human readable error message.

LineItem¶

jsonparam BigDecimal amount:

(required) The total price of the order.

jsonparam String amount:

(required) The description of the order or the item in the order.

jsonparam Integer amount:

(required) The total quantity of the items being ordered.

For use in the Stripe Hosted Guest Website EGift Checkout page, the LineItem should always have the format as below:

{
     "amount": [the total cart price],
     "description": "egift card(s)",
     "quantity": 1
}

CheckoutSession¶

JSON Parameters:
	id (String) – (required) The ID associated with the checkout session. paymentIntent (PaymentIntent) – (required) The payment intent ID associated with the checkout session. redirectUrl (String) – (required) The redirectUrl to launch the stripe hosted checkout page.

PaymentIntent¶

JSON Parameters:

id (String) – (required) The ID associated with the payment intent
amount (BigDecimal) – (required) The total amount of the transaction represented by the payment intent.
chargeInfo (ChargeResponse) – (optional) See ChargeResponse for format of the object.
status (PaymentIntentStatusEnum.Value) – (optional) See PaymentIntentStatusEnum for format of the object.
billingAddress (Address) – (optional) See Address for format of the object.
guestName (String) – (optional) The name of the guest paying for the transaction.
guestPhone (String) – (optional) The phone number of the guest paying for the transaction.

PaymentIntentStatusEnum¶

Can have the following Values:

REQUIRES_PAYMENT_METHOD
REQUIRES_CONFIRMATION
REQUIRES_ACTION
PROCESSING
REQUIRES_CAPTURE
CANCELED
SUCCEEDED

ApplePayMerchantSession¶

JSON Parameters:
	merchantSession (String) – (required) The merchant session returned by Apple to pass to completeMerchantValidation for Apple Pay.

ApplePayMerchantDetails¶

JSON Parameters:

domainNames (List[String]) – (required) The list of domains registered for Apple Pay for this merchant.
partnerMerchantName (String) – (required) The name of the Merchant as stored in the PXS.
partnerInternalMerchantIdentifier (String) – (required) The merchant specific Paytronix identifier as provided by Apple.
partnerMerchantValidationURI (String) – (required) The domain verification file location for merchant.
encryptTo (String) – (required) The Paytronix Apple identifier hash.
merchantUrl (String) – (required) The merchant’s default domain as stored in the PXS

Error Codes ¶

The following are the possible codes and messages that can be returned by the Payment Service.

There are other system-level errors which may be returned which are not documented here.

The caller of the endpoint can use the returned message to display to the end user or, if different wording is desired, can provide their own mapping of code to message.

Code	Message
`recharge.error`
`recharge.amount_below_minimum`	Recharge amount is below allowed minimum for this card
`recharge.amount_above_maximum`	Recharge amount is above allowed maximum for this card
`recharge.no_matching_saved_card`	No matching saved card found
`recharge.invalid_payment_method`	Specified payment method cannot be used to recharge stored value
`recharge.not_configured`	Recharge is not configured or not enabled for this type of card
`recharge.invalid_merchant_id`	Invalid merchant ID
`recharge.auto_recharge_not_enabled`	Auto recharge is not enabled for this merchant
`recharge.invalid_card_number`	Invalid card number
`recharge.card_not_active`	Card not active
`recharge.no_sv_wallet`	This merchant does not have a Stored Value wallet
`recharge.no_sv_wallet_attached`	This card does not have a Stored Value wallet attached
`recharge.error_loading_account_data`	Error loading account data
`recharge.account_not_active`	Account not active
`recharge.error_loading_user_data`	Error loading user
`recharge.no_email_address`	User does not have an email address defined
`recharge.email_not_verified`	User’s email address must be verified in order to recharge
`recharge.error_loading_cc_processor_data`	Error loading CC processor data
`recharge.recharge_prevent`	Account’s ability to recharge is disabled
`recharge.server_error`	Internal server error
`recharge.not_accepting_enrollees`	This recharge program is not accepting new enrollees
`recharge.invalid_cc_type`	Specified Credit Card Type is not allowed for this program
`recharge.cc_auth_declined`	Credit card authorization was declined
`recharge.sv_wallet_adjust_failed`	Error adjusting Stored Value wallet
`recharge.sv_wallet_adjust_denied`	Stored Value wallet adjustment was denied
`recharge.cc_capture_declined`	Credit transaction capture was declined
`payment_config.error`
`payment_config.not_configured`	Recharge is not configured for this combination of merchantId and cardTemplateCode
`payment_config.server_error`	Internal server error
`payment_config.invalid_merchant_id`	Invalid merchant ID
`payment_config.invalid_card_template_code`	Invalid cardTemplateCode
`saved_card.error`
`saved_card.server_error`	Internal server error
`saved_card.invalid_merchant_id`	Invalid merchant ID
`saved_card.invalid_card_number`	Invalid card number
`saved_card.card_not_active`	Card not active
`saved_card.error_loading_account_data`	Error loading account data
`saved_card.account_not_active`	Account not active
`saved_card.no_saved_card`	No saved card
`saved_card.saved_card_expired`	Saved card is expired
`recharge_history.server_error`	Internal server error
`recharge_history.error`
`recharge_history.invalid_merchant_id`	Invalid merchant ID
`recharge_history.invalid_card_number`	Invalid card number
`recharge_history.card_not_active`	Card not active
`recharge_history.error_loading_account_data`	Error loading account data
`recharge_history.account_not_active`	Account not active
`add_saved_credit_card.add_saved_credit_card_failed`	Account not active
`auto_recharge_disable.error`	Failed to add saved credit card
`auto_recharge_disable.server_error`	Internal server error
`auto_recharge_disable.invalid_merchant_id`	Invalid merchant ID
`auto_recharge_disable.invalid_card_number`	Invalid card number
`auto_recharge_disable.card_not_active`	Card not active
`auto_recharge_disable.error_loading_account_data`	Error loading account data
`auto_recharge_disable.account_not_active`	Account not active
`auto_recharge_disable.not_enrolled`	Account is not enrolled in auto recharge
`auto_recharge_disable.auto_recharge_not_active`	Auto recharge is not enabled for this account
`auto_recharge_enable_monitoring.error`
`auto_recharge_enable_monitoring.server_error`	Internal server error
`auto_recharge_enable_monitoring.invalid_merchant_id`	Invalid merchant ID
`auto_recharge_enable_monitoring.invalid_printed_card_number`	Invalid card number
`auto_recharge_enable_monitoring.card_not_active`	Card not active
`auto_recharge_enable_monitoring.error_loading_account_data`	Error loading account data
`auto_recharge_enable_monitoring.account_not_active`	Account not active
`auto_recharge_enable_monitoring.not_configured`	Auto recharge is not configured or not enabled for this type of card
`auto_recharge_enable_monitoring.monitoring_only_not_enabled`	Monitoring only auto recharge is not enabled for this merchant
`auto_recharge_enable_monitoring.not_accepting_enrollees`	This recharge program is not accepting new enrollees
`auto_recharge_enable_monitoring.amount_below_minimum`	Recharge amount is below allowed minimum for this card
`auto_recharge_enable_monitoring.amount_above_maximum`	Recharge amount is above allowed maximum for this card
`auto_recharge_enable_monitoring.account_disabled_by_csr`	Auto recharge for this account is disabled by CSR
`auto_recharge_get_pending_auto_recharges.error`
`auto_recharge_get_pending_auto_recharges.server_error`	Internal server error
`auto_recharge_get_pending_auto_recharges.invalid_merchant_id`	Invalid merchant ID
`auto_recharge_get_pending_auto_recharges.not_configured`	Auto recharge is not configured or not enabled for this merchant
`auto_recharge_get_pending_auto_recharges.monitoring_only_not_enabled`	Monitoring only auto recharge is not enabled for this merchant
`cc_transaction.invalid_input`	Invalid Credit Card information
`cc_transaction.error`
`recharge.invalid_merchant_id`	Invalid merchant ID
`cc_transaction.error_loading_cc_processor_data`	Error loading CC processor data
`recharge.server_error`	Internal server error
`cc_transaction.invalid_cc_type`	Specified Credit Card Type is not allowed for this program
`delete_saved_card.invalid_saved_card_code`	Invalid saved card code
`delete_saved_card.invalid_merchant_id`	Invalid merchant ID
`delete_saved_card.invalid_printed_card_number`	Invalid printed card number
`delete_saved_card.saved_card_not_found`	Saved credit card not found
`delete_saved_card.server_error`	Internal server error
`delete_saved_card.auto_recharge_enabled`	Cannot delete saved credit card while auto recharge is enabled. Use autoRechargeDisable resource instead
`delete_saved_card.account_not_active`	Account not active
`delete_saved_card.card_not_active`	Card not active
`delete_payment_method.system_error`	System error
`payment_method.system_error`	System error
`saved_payment_method.system_error`	System error
`saved_payment_methods.system_error`	System error