Quickstart

Prerequisites

Before you start, make sure you have:

• A Jupico platform account or access to the shared public sandbox credentials (see below).

• A sandbox sub-merchant ID.

• A server-side environment where you can safely store API credentials.

• A front-end page where you can render Jupico web components.

• A local or hosted HTTPS environment for wallet testing when using Apple Pay or Google Pay.

⚠️

Never expose Jupico API credentials in browser code, mobile applications, logs, or client-side configuration.

1. Choose an environment

Jupico uses separate sandbox and production environments.

Sandbox can be used to validate account setup, tokenization, transactions, and payout flows before production access is enabled.

Use the public sandbox credentials below for exploration, then replace them with platform-specific sandbox and production credentials as soon as your account is provisioned.

ZGVtb0FwaVVzZXI6VjhtIXhQI2wyUXoz

demoApiUser

V8m!xP#l2Qz3

Note: The credentials above are for a shared account used by multiple developers, therefore the sandbox environment is reset every 24 hours. If using unique sandbox credentials (I.e existing users), your environment will not reset every 24 hours.

Once your platform signs up, you will receive your own set of credentials for the sandbox and production environments, specific to your platform. Different levels of permissions can be set to grant key access and capabilities to each API (transactions, reporting, provisioning, etc).

2. Authenticate API requests

Jupico API requests use Basic authentication. Send the Authorization header on every server-to-server API call.

Note: All requests must be made over HTTPS and will be authenticated using standard HTTP basic authentication.

• Calls made over plain HTTP will fail
• Requests without authentication will also fail

curl --location --request GET 'https://sandbox-platform.jupico.com/status' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ZGVtb0FwaVVzZXI6VjhtIXhQI2wyUXoz' \
--data-raw ''

Authentication requires a username and a password. When prompted for credentials in a console/terminal, programming libraries, SDKs, or within our documentation, please use the following username and password:

3. Create or identify a sub-merchant

Most payment operations require a subMerchantId. In sandbox, you can use a provided test sub-merchant. In production, a merchant must be onboarded and approved before it can process payments or receive payouts.

Use the onboarding guides to choose the best setup:

• Hosted onboarding for the fastest launch.
• Flex onboarding for a branded hosted experience.
• API onboarding / Provisioning API when your platform owns the merchant onboarding UI and submits data to Jupico.

Sub-Merchant Sandbox Test Data

4. Create a browser authorization session

Before rendering a web component, your backend creates a browser authorization session. The session tells the component which sub-merchant, payment methods, amount, and configuration to use.

curl --location 'https://sandbox-platform.jupico.com/v1/sessions/browser/authorize' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <base64-encoded-credentials>' \
  --data '{
    "subMerchantId": "<submerchant-id>",
    "cardTokenization": { "enabled": true },
    "bankAccountTokenization": { "enabled": true },
    "applePay": { "enabled": false },
    "googlePay": { "enabled": false }
  }'

Return the session object to your front end. Use the same session object for all payment components on that payment page unless the payment context changes.

5. Render a payment method component

On the client side, load the Jupico web component bundle and render the component that matches your payment flow.

• For card acceptance, use the credit card form component.
• For ACH/eCheck, use the bank account form component.
• For wallets, use Apple Pay or Google Pay components with wallet configuration enabled in the authorization session.

The component collects sensitive payment details directly through Jupico-controlled tokenization logic and returns a token to your application.

6. Run a test transaction

After tokenization succeeds, send the returned payment token to your backend. Your backend can then create a sale or authorization request through the Transaction API.

Use:

• Sale when the amount is known and you want to charge immediately.
• Authorization when you want to place a hold and capture later.
• Capture to complete a prior authorization.
• Void to cancel an unsettled transaction.
• Refund to return funds after settlement.

Sandbox Credit Card Tokens

Credit Card Brands

Cardholder Name: Any
Expiration Date: 12/25
CVV: 123

7. Confirm operational behavior

Before moving out of the quickstart, confirm that you can:

• See the test transaction in reporting or Backoffice.
• Query transaction status from your backend.
• Handle decline and validation errors cleanly.
• Store only non-sensitive tokens and identifiers.
• Confirm the expected payout mode for the sub-merchant.
• Receive and validate any relevant web-hook events.

Error Handling

Jupico uses conventional HTTP response codes to indicate the success or failure of an API request:

• Codes in the 2xx range indicate success.

• Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).

• Codes in the 5xx range indicate an error with Jupico's servers (these are rare).

Some 4xx errors that could be handled programmatically, include an error code that briefly explains the error reported.