Process a card sale

curl --request POST \
  --url https://sandbox-platform.jupico.com/v1/transactions/creditcard/sale \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subMerchantId": "jpt-sim-md-1",
  "paymentToken": {
    "type": "creditcard",
    "token": {
      "provider": "jupico",
      "token": "5dd19881-b437-42b0-9c9b-7773ebb598eb"
    }
  },
  "amount": 40,
  "cardHolderInitiated": true
}
'

{
  "success": true,
  "data": {
    "status": "<string>",
    "transactionId": "<string>",
    "approvalNumber": "<string>",
    "operation": "<string>",
    "subMerchantId": "<string>",
    "amount": 123,
    "txDate": "<string>",
    "referenceNumber": "<string>",
    "referenceId": "<string>",
    "taxAmount": 123,
    "taxWithHold": true,
    "items": [
      {
        "description": "Consulting services",
        "quantity": 5,
        "amount": 100,
        "taxRate": 123
      }
    ],
    "balanceAmount": 123,
    "parentId": "<string>",
    "description": "<string>",
    "dynamicFee": {
      "discountRatePerc": 123,
      "fixed": 123
    },
    "paymentMethod": {
      "type": "<string>",
      "eCheck": {},
      "cc": {
        "card": {
          "cardHolderName": "<string>",
          "last4Digits": "<string>",
          "expirationMonth": "<string>",
          "expirationYear": "<string>",
          "logo": "<string>"
        },
        "provider": "<string>",
        "cardHolderInitiated": true,
        "networkTransactionID": "<string>",
        "token": "<string>"
      }
    },
    "billing": {
      "name": "<string>",
      "email": "<string>",
      "address": "<string>",
      "city": "<string>",
      "zipCode": "<string>",
      "state": "<string>",
      "country": "<string>",
      "phone": "<string>"
    },
    "shipping": {
      "address": "<string>",
      "city": "<string>",
      "zipCode": "<string>",
      "state": "<string>",
      "country": "<string>",
      "email": "<string>",
      "name": "<string>",
      "phone": "<string>"
    },
    "validations": {
      "avs": {
        "addressNumber": "<string>",
        "addressPostalCode": "<string>"
      },
      "cvv": {
        "cvcCheck": "<string>"
      }
    },
    "paymentToken": {
      "type": "<string>",
      "token": {
        "provider": "<string>",
        "token": "<string>",
        "cardHolderName": "<string>",
        "expirationMonth": "<string>",
        "expirationYear": "<string>",
        "logo": "<string>",
        "cardLogo": "<string>",
        "last4Digits": "<string>",
        "truncatedCardNumber": "<string>"
      }
    }
  },
  "message": "<string>",
  "code": "<string>"
}

POST

https://sandbox-platform.jupico.com

transactions

creditcard

sale

curl --request POST \
  --url https://sandbox-platform.jupico.com/v1/transactions/creditcard/sale \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subMerchantId": "jpt-sim-md-1",
  "paymentToken": {
    "type": "creditcard",
    "token": {
      "provider": "jupico",
      "token": "5dd19881-b437-42b0-9c9b-7773ebb598eb"
    }
  },
  "amount": 40,
  "cardHolderInitiated": true
}
'

{
  "success": true,
  "data": {
    "status": "<string>",
    "transactionId": "<string>",
    "approvalNumber": "<string>",
    "operation": "<string>",
    "subMerchantId": "<string>",
    "amount": 123,
    "txDate": "<string>",
    "referenceNumber": "<string>",
    "referenceId": "<string>",
    "taxAmount": 123,
    "taxWithHold": true,
    "items": [
      {
        "description": "Consulting services",
        "quantity": 5,
        "amount": 100,
        "taxRate": 123
      }
    ],
    "balanceAmount": 123,
    "parentId": "<string>",
    "description": "<string>",
    "dynamicFee": {
      "discountRatePerc": 123,
      "fixed": 123
    },
    "paymentMethod": {
      "type": "<string>",
      "eCheck": {},
      "cc": {
        "card": {
          "cardHolderName": "<string>",
          "last4Digits": "<string>",
          "expirationMonth": "<string>",
          "expirationYear": "<string>",
          "logo": "<string>"
        },
        "provider": "<string>",
        "cardHolderInitiated": true,
        "networkTransactionID": "<string>",
        "token": "<string>"
      }
    },
    "billing": {
      "name": "<string>",
      "email": "<string>",
      "address": "<string>",
      "city": "<string>",
      "zipCode": "<string>",
      "state": "<string>",
      "country": "<string>",
      "phone": "<string>"
    },
    "shipping": {
      "address": "<string>",
      "city": "<string>",
      "zipCode": "<string>",
      "state": "<string>",
      "country": "<string>",
      "email": "<string>",
      "name": "<string>",
      "phone": "<string>"
    },
    "validations": {
      "avs": {
        "addressNumber": "<string>",
        "addressPostalCode": "<string>"
      },
      "cvv": {
        "cvcCheck": "<string>"
      }
    },
    "paymentToken": {
      "type": "<string>",
      "token": {
        "provider": "<string>",
        "token": "<string>",
        "cardHolderName": "<string>",
        "expirationMonth": "<string>",
        "expirationYear": "<string>",
        "logo": "<string>",
        "cardLogo": "<string>",
        "last4Digits": "<string>",
        "truncatedCardNumber": "<string>"
      }
    }
  },
  "message": "<string>",
  "code": "<string>"
}

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json

API support various types of use. Required fields are defined by the most basic call. For other uses be sure to send the required information defined in the schema and examples.

subMerchantId

string

required

Unique identifier of the submerchant.

amount

number

required

The amount to charge.

paymentToken

object

required

The payment credential to charge: a one-time token from the web component or a stored Jupico token.

Hide child attributes

paymentToken.type

string

Type of token supplied.

paymentToken.token

object

Token payload returned by tokenization.

cardHolderInitiated

boolean

required

True when the cardholder actively initiates the payment; false for merchant-initiated transactions such as recurring charges.

items

object[]

Line items included in the total amount.

Hide child attributes

items.description

string

Description of the line item.

items.quantity

number

Number of units.

items.amount

number

Price per unit.

items.taxRate

number

Tax rate applied to this line item, as a percentage.

description

string

Free-text description of the transaction.

taxAmount

number

The total amount of sales tax must be between: Visa: 0.1% - 18% MasterCard: 0.1% - 23% Default: 0.1% - 50%

taxWithHold

boolean

When true, the sales tax portion is withheld from the merchant's settlement until released.

dynamicFee

Dynamic fee · object

Defines the platform fee that the service provider charges the merchant for the transaction. The fee is calculated using fixed and discountRatePerc and deducted from the merchant's transaction proceeds when payouts are calculated. It does not increase or otherwise modify the transaction amount submitted for processing.

Hide child attributes

dynamicFee.fixed

number

Fixed monetary portion of the platform fee, in the transaction currency.

dynamicFee.discountRatePerc

number

Percentage portion of the platform fee, calculated from the transaction amount.

processingDynamicFee

Dynamic processing fee · object

Defines the payment-processing fee that the service provider charges the merchant for the transaction. The fee is calculated using the supported fixed and percentage values, deducted from the merchant's transaction proceeds, and accounted for separately from the platform fee. It does not increase or otherwise modify the transaction amount submitted for processing.

Hide child attributes

processingDynamicFee.fixed

number

Fixed monetary portion of the processing fee, in the transaction currency.

processingDynamicFee.discountRatePerc

number

Percentage portion of the processing fee, calculated from the transaction amount.

cvv

string

Card verification code (CVV/CVC).

referenceId

string

Your own reference for this transaction. Returned in responses and query results for reconciliation.

billing

object

Billing contact and address details for the payer.

Hide child attributes

billing.address

string

Street address, including number.

billing.city

string

City name.

billing.zipCode

string

ZIP or postal code.

billing.state

string

Two-letter US state code.

billing.country

string

Two-letter ISO 3166-1 country code. Sets which state codes and postal code format are validated.

billing.email

string

Email address of the payer.

billing.name

string

Full name of the payer.

billing.phone

string

Phone number of the payer.

shipping

object

Shipping contact and address details for the order.

Hide child attributes

shipping.address

string

Street address, including number.

shipping.city

string

City name.

shipping.zipCode

string

ZIP or postal code.

shipping.state

string

Two-letter US state code.

shipping.country

string

Two-letter ISO 3166-1 country code. Sets which state codes and postal code format are validated.

shipping.email

string

Email address of the recipient.

shipping.name

string

Name of the recipient.

shipping.phone

string

Phone number of the recipient.

metadata

object

metadata is an object that can host as much as 50 key-value pairs, where the keys can be at most 40 char length and can’t include the characters “[“ or “]”, and the values must be strings and cannot exceed 500 chars Learn more about metadata

Hide child attributes

metadata.{key}

string

Maximum string length: 500

billingDescriptor

object

Overrides the descriptor that appears on the cardholder's statement.

Hide child attributes

billingDescriptor.name

string

The text that appears on the cardholder's statement, overriding the default business name.

Maximum string length: 25

Example:

"test"

Response

200 - application/json

Successful sale

success

boolean

Whether the request was processed successfully. Declines return HTTP 200 with success: false.

data

object

The response payload.

Hide child attributes

data.status

string

Current status.

data.transactionId

string

Unique identifier of the original transaction.

data.approvalNumber

string

Approval code returned by the issuing bank.

data.operation

string

Transaction operation type (for example, sale, authorization, refund).

data.subMerchantId

string

Unique identifier of the submerchant.

data.amount

number

The amount of the transaction.

data.txDate

string

Date and time of the transaction (ISO 8601).

data.referenceNumber

string

Processor reference number for the transaction.

data.referenceId

string

Your own reference for this transaction. Returned in responses and query results for reconciliation.

data.taxAmount

number

Sales tax portion of the amount.

data.taxWithHold

boolean

When true, the sales tax portion is withheld from the merchant's settlement until released.

data.items

object[]

Line items included in the total amount.

Hide child attributes

data.items.description

string

Description of the line item.

Example:

"Consulting services"

data.items.quantity

number

Number of units.

Example:

5

data.items.amount

number

Price per unit.

Example:

100

data.items.taxRate

number

Tax rate applied to this line item, as a percentage.

data.balanceAmount

number

Remaining balance on the transaction after captures, refunds, and voids.

data.parentId

string

Identifier of the parent transaction (for example, the authorization behind a capture).

data.description

string

Free-text description.

data.dynamicFee

object

Hide child attributes

data.dynamicFee.discountRatePerc

number

Percentage portion of the platform fee, calculated from the transaction amount.

data.dynamicFee.fixed

number

Fixed monetary portion of the platform fee, in the transaction currency.

data.paymentMethod

object

Details of the payment method used.

Hide child attributes

data.paymentMethod.type

string

The type.

data.paymentMethod.eCheck

object

eCheck (ACH) acceptance settings.

data.paymentMethod.cc

object

Card payment method details.

Hide child attributes

data.paymentMethod.cc.card

object

Card details.

Hide child attributes

data.paymentMethod.cc.card.cardHolderName

string

Name of the cardholder.

data.paymentMethod.cc.card.last4Digits

string

Last 4 digits of the card number.

data.paymentMethod.cc.card.expirationMonth

string

Two-digit expiration month (01-12).

data.paymentMethod.cc.card.expirationYear

string

Two-digit expiration year.

data.paymentMethod.cc.card.logo

string

Card brand logo identifier.

data.paymentMethod.cc.provider

string

Payment provider that issued the token.

data.paymentMethod.cc.cardHolderInitiated

boolean

True when the cardholder actively initiates the payment; false for merchant-initiated transactions such as recurring charges.

data.paymentMethod.cc.networkTransactionID

string

Card network transaction identifier, used for merchant-initiated follow-on transactions.

data.paymentMethod.cc.token

string

The token value.

data.billing

object

Billing contact and address details for the payer.

Hide child attributes

data.billing.name

string

Full name of the payer.

data.billing.email

string

Email address of the payer.

data.billing.address

string

Street address, including number.

data.billing.city

string

City name.

data.billing.zipCode

string

ZIP or postal code.

data.billing.state

string

Two-letter US state code.

data.billing.country

string

Two-letter ISO 3166-1 country code.

data.billing.phone

string

Phone number of the payer.

data.shipping

object

Shipping contact and address details for the order.

Hide child attributes

data.shipping.address

string

Street address, including number.

data.shipping.city

string

City name.

data.shipping.zipCode

string

ZIP or postal code.

data.shipping.state

string

Two-letter US state code.

data.shipping.country

string

Two-letter ISO 3166-1 country code.

data.shipping.email

string

Email address of the recipient.

data.shipping.name

string

Name of the recipient.

data.shipping.phone

string

Phone number of the recipient.

data.validations

object

Verification results returned by the issuer.

Hide child attributes

data.validations.avs

object

Address Verification Service (AVS) results.

Hide child attributes

data.validations.avs.addressNumber

string

AVS result for the street number.

data.validations.avs.addressPostalCode

string

AVS result for the postal code.

data.validations.cvv

object

CVV check result.

Hide child attributes

data.validations.cvv.cvcCheck

string

Result of the card verification code check.

data.paymentToken

object

The payment credential to charge: a one-time token from the web component or a stored Jupico token.

Hide child attributes

data.paymentToken.type

string

Type of token supplied.

data.paymentToken.token

object

Token payload returned by tokenization.

Hide child attributes

data.paymentToken.token.provider

string

Payment provider that issued the token (for example, jupico).

data.paymentToken.token.token

string

The token value.

data.paymentToken.token.cardHolderName

string

Name of the cardholder.

data.paymentToken.token.expirationMonth

string

Two-digit expiration month (01-12).

data.paymentToken.token.expirationYear

string

Two-digit expiration year.

data.paymentToken.token.logo

string

Card brand logo identifier.

data.paymentToken.token.cardLogo

string

Card brand logo identifier.

data.paymentToken.token.last4Digits

string

Last 4 digits of the card number.

data.paymentToken.token.truncatedCardNumber

string

Masked card number.

message

string

Human-readable result message.

code

string

Machine-readable result code. See the Error Codes reference.

API Overview

API Reference

Resources

Process a card sale

Authorizations

Body

Response