# Credit or Debit card

Learn how to accept online payments by credit or debit card using the Stark Bank platform.

We use a resource called Merchant Purchase to represent each card payment. In this guide, you'll learn how to manage the main use cases and understand the payment life cycle.

Since sensitive card data should never pass through your server, we created the Merchant Session. It lets you set up a secure, temporary session so your website or app can send card details directly to Stark Bank.

After a purchase is created, Stark Bank splits it into one or more installments — even single payments get one — so you can track exactly when each amount will land in your account.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

Merchant PurchaseThe card payment you charge your customer.Merchant InstallmentEach scheduled payment from a purchase, credited to your account.Merchant SessionSecure session that lets your website send card data directly to Stark Bank.Merchant CardSaved card details for repeat purchases.

## Setup

For each environment (Sandbox or Production):

1. Create an account at Stark Bank.

2. Create a webhook with the following subscriptions to receive events at your desired URL:

merchant-purchase

merchant-installment

merchant-card

2.1. Via Internet Banking: 

Integrations > Webhook > New Webhook

2.2. Via API: 

Use the POST /webhook route to create the webhook

## Payment Flows

There are three main ways to accept a card payment with Stark Bank:

Standard checkout (most common): Create a Merchant Session on your server, then collect the card details on your website or app and submit the purchase directly to Stark Bank. This flow doesn't require PCI compliance. See Merchant Session and Merchant Purchase below.

3DS checkout (adds an extra security step): Works the same as a standard checkout, but the cardholder confirms the payment through their bank before it's approved. To enable it, when creating the session: challengeMode="enabled"

Repeat charges (requires a prior approved purchase): After a customer's first payment, their card is saved as a Merchant Card. You can use it to charge them again without collecting card details — great for subscriptions or returning customers. See Merchant Card and Creating a Merchant Purchase via API below.

## Sandbox

The Sandbox environment simulates all card payment behaviors — approvals, declines, 3DS challenges, and errors — without real cards or charges. Use it to test your full integration before going live.

Sandbox vs Production: Stark Bank uses separate workspaces for each environment, each with its own URL and API keys. Changes in one environment don't affect the other.

If you don't have a Sandbox workspace yet, create one here:

Create a Workspace in Sandbox

## Test Cards

Use the card numbers below to simulate different payment scenarios in the Sandbox environment. All test cards accept any future expiration date and any 3-digit CVC.

| Scenario | Card Number | Expected Behavior |
| --- | --- | --- |
| Successful payment | 4242 4242 4242 4242 | Purchase is approved and confirmed. |
| 3DS challenge | 5500 0000 0000 0004 | Triggers 3DS verification flow. Requires challengeMode enabled |
| Declined — insufficient funds | 4000 0000 0000 0002 | Purchase is denied with reason: insufficient funds. |
| Declined — generic | 5105 1051 0510 5100 | Purchase is denied by the issuer bank. |
| Expired card | 3782 822463 10005 | Purchase fails due to expired card. |
| Incorrect CVC | 3714 496353 98431 | Purchase fails due to incorrect security code. |

## Merchant Session Overview

If your website or app needs to collect card details from customers — without those details ever touching your server — you should create a Merchant Session. This is the recommended approach for most integrations.

A Merchant Session works in two steps. First, your server creates a session via the Stark Bank API, defining the allowed funding types, installment options, expiration, and 3DS challenge mode. You'll receive a session object with a unique UUID.

Then, your client-side uses that UUID to submit the purchase along with the cardholder's sensitive data (card number, expiration, security code, holder info, billing address, and browser metadata) directly to Stark Bank — so card data never touches your backend.

Once a card is used successfully through a Merchant Session Purchase, it's stored as a Merchant Card and can be reused in future purchases without a new session.

### Creating a Merchant Session

To create a Merchant Purchase, you first need to create a Merchant Session on your server.

The session defines the purchase parameters such as the allowed funding types, installment options, expiration, and amount. You'll receive a UUID that your client-side will use to submit the purchase.

### Creating a 3DS Merchant Session

To create a Merchant Purchase with 3DS authentication, you need to create a Merchant Session with the field 'challengeMode' set to 'enabled'.

3DS (3-D Secure) adds an extra verification step where the cardholder confirms the payment through their bank — similar to a two-factor authentication for card payments. Apart from the 'challengeMode' field, the session creation is identical to a regular Merchant Session.

### Creating a Zero Dollar Merchant Session

A zero dollar Merchant Session is used to validate a card without charging the cardholder.

To create one, the field 'allowedInstallments' must contain just one option with 'totalAmount' equal to '0' and 'count' equal to '1', as in the example below.

## Merchant Card Overview

A Merchant Card stores card information for use in future recurring purchases.

### The Merchant Card object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the merchant card. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `ending` | STRING | Last 4 digits of the card number. |
| `expiration` | STRING | Card expiration date. Example: "2025-06". |
| `fundingType` | STRING | Funding type. Options: "credit", "debit". |
| `holderName` | STRING | Name of the card holder. |
| `network` | STRING | Card network. |
| `status` | STRING | Current card status. Options: "active", "expired", "canceled", "blocked". |
| `tags` | LIST OF STRINGS | Tags associated with the card. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Getting Merchant Cards

You can query Merchant Cards using tags to find cards associated with a specific customer.

When creating a Merchant Card, assign a tag that identifies the customer. Later, use the tags parameter to retrieve all cards linked to that customer.

### Receiving Card Webhook

Listen to Card Webhooks

After creation, you can use webhooks to monitor status changes.

Every time a Merchant Card changes, we create a Log. Logs are useful for understanding the life cycle of each Merchant Card. Whenever a new Log is created, we'll send a webhook to your registered URL.

## Merchant Purchase Overview

A Merchant Purchase represents a card payment charged to your customer. It can be created in two ways: through a Merchant Session, where your client-side submits the purchase directly to Stark Bank using the session UUID; or via the API using a Merchant Card ID for recurring charges.

After creation, the purchase follows a life cycle: it starts as created, moves to approved once the card network authorizes it, and is finally confirmed when the payment is settled. You can also cancel an approved purchase or reverse a confirmed one, either partially or fully.

Each Merchant Purchase generates one or more Merchant Installments, which represent the individual payments that will be credited to your account.

### The Merchant Purchase object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the merchant purchase. |
| `amount` | INTEGER | Amount in cents to be received. Example: 100 (R$1.00). |
| `cardEnding` | STRING | Last 4 digits of the card. |
| `cardId` | STRING | ID of the Merchant Card used for the purchase. |
| `challengeMode` | STRING | Holder verification mode. Options: "enabled", "disabled". |
| `challengeUrl` | STRING | URL for holder verification challenge. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `currencyCode` | STRING | Currency code of the purchase. |
| `endToEndId` | STRING | End-to-end ID of the purchase. |
| `fee` | INTEGER | Fee charged in cents. |
| `fundingType` | STRING | Funding type. Options: "credit", "debit". |
| `installmentCount` | INTEGER | Number of purchase installments. |
| `network` | STRING | Card network. |
| `source` | STRING | Source of the purchase. |
| `status` | STRING | Current purchase status. Options: "created", "approved", "denied", "confirmed", "paid", "pending", "canceled", "voided", "failed". |
| `tags` | LIST OF STRINGS | Tags associated with the purchase. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### The Merchant Purchase Status

A Merchant Purchase has the following life cycle:

| Status | Description |
| --- | --- |
| Created | The Merchant Purchase was created in Stark Bank. |
| Pending | Waiting for the user to complete 3DS verification. This only applies if you enabled 3DS. |
| Approved | The issuer bank accepted the purchase. |
| Denied | The issuer bank denied the purchase. |
| Failed | The purchase failed. |
| Confirmed | The payment was confirmed and will be credited to your account. |
| Paid | All installments were paid to your account. |
| Canceled | The purchase was canceled by you. |
| Void | The purchase was fully reversed. |

### The Merchant Purchase Logs

Every time a Merchant Purchase changes, we create a Log. Logs are useful for understanding the life cycle of each purchase. Whenever a new Log is created, we'll send a webhook to your registered URL.

Check out this diagram to understand the possible Merchant Purchase Logs:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Merchant Purchase was successfully created in Stark Bank. |
| Pending | Pending | The Merchant Purchase is waiting for the user to complete 3DS verification. |
| Approved | Approved | The Merchant Purchase was authorized by the issuer bank. |
| Denied | Denied | The Merchant Purchase was denied by the issuer bank. |
| Failed | Failed | The Merchant Purchase processing failed. |
| Confirmed | Confirmed | The Merchant Purchase payment was confirmed and will be credited to your account. |
| Canceling | Approved | The Merchant Purchase cancellation is being processed. |
| Canceled | Canceled | The Merchant Purchase was canceled. |
| Paid | Paid | All installments of the Merchant Purchase were paid to your account. |
| Reversing | Confirmed | The Merchant Purchase reversal is being processed. |
| Reversed | Confirmed | The Merchant Purchase was partially reversed. |
| Voided | Voided | The Merchant Purchase was fully reversed. |

Note: You only receive these webhooks if you have the merchant-purchase subscription set.

### Creating a Merchant Purchase via Session

After creating a Merchant Session, you can create a purchase using the UUID generated in the session through a public route. This means the transaction does not need to go through your backend.

Note: the UUID serves as a unique key that allows us to associate the purchase your client is creating directly with your merchant account.

### Creating a 3DS Merchant Purchase via Session

After creating a 3DS Merchant Session, you can create a purchase using the UUID generated in the session through a public route. This transaction does not need to go through your backend.

To create a merchant purchase with the 3DS protocol, you need to fill in the fields: 'billingCity', 'billingCountryCode', 'billingStateCode', 'billingStreetLine1', 'billingStreetLine2', 'billingZipCode', 'holderEmail', 'holderPhone'.

You also need to send the 'metadata' object, which must contain these fields: 'userAgent', 'userIp' and 'language'.

### Creating a Zero Dollar Merchant Purchase via Session

After creating a zero dollar Merchant Session, you can create a purchase using the UUID generated in the session through a public route. This transaction does not need to go through your backend.

To create a zero dollar merchant purchase, you only need to set the field 'amount' to '0'.

### Creating a Merchant Purchase via API

To create a purchase directly from your server, use the POST /merchant-purchase endpoint with a Merchant Card ID for recurring charges.

For this integration, you must already have an approved purchase with this card. After the purchase is approved, an entity called Merchant Card is generated and you can use it for recurring purchases.

The only field you need from the Merchant Card is its ID. You can check it by consulting an approved Merchant Purchase or using the endpoint to list the Merchant Cards.

### Querying Merchant Purchases

You can retrieve a Merchant Purchase by its ID or list them using parameters such as limit, after, before to filter the results, as shown in the example below:

You can also query Merchant Purchases using tags to find purchases associated with a specific order. When creating a Merchant Purchase, assign a tag with the order ID. Later, use the tags parameter to retrieve all purchases linked to that order.

### Canceling a Merchant Purchase

To cancel a Merchant Purchase, its status must be approved. The amount is set to 0, which cancels the authorization.

While the cancellation is being processed, the purchase status remains approved.

### Partially Reversing a Merchant Purchase

Partial reversals are only allowed one day after the purchase confirmation.

To partially reverse a Merchant Purchase, its status must be confirmed. This action debits the difference and reverses part of the purchase.

While the reversal is being processed, the purchase status remains confirmed. After the partial reversal is completed, the status also remains confirmed.

### Fully Reversing a Merchant Purchase

To fully reverse a Merchant Purchase, its status must be confirmed. This action reverses the entire purchase amount.

While the reversal is being processed, the purchase status remains confirmed. After the full reversal is completed, the status changes to voided.

### Receiving Purchase Webhook

Approved Webhook Example

## Merchant Installment Overview

When you create a Merchant Purchase, you can choose to receive it in one installment or split it into multiple installments.

Each installment is tracked as a Merchant Installment, which helps you monitor when each payment is due and which ones have already been credited.

Once an installment is paid, you'll receive a credit log with the transaction ID that appears on your statement.

### The Merchant Installment object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the merchant installment. |
| `amount` | INTEGER | Installment amount in cents. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `due` | STRING | Expected settlement date. Example: "2020-04-23T23:00:00.000000+00:00". |
| `fee` | INTEGER | Fee charged in cents. |
| `fundingType` | STRING | Funding type. Options: "credit", "debit". |
| `network` | STRING | Card network. |
| `purchaseId` | STRING | ID of the Merchant Purchase linked to the installment. |
| `status` | STRING | Current installment status. Options: "created", "paid", "canceled", "voided". |
| `tags` | LIST OF STRINGS | Tags associated with the installment. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the installment. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### The Merchant Installment Status

A Merchant Installment has the following life cycle:

| Status | Description |
| --- | --- |
| Created | The Merchant Installment was created. |
| Paid | The Merchant Installment was paid to your account. |
| Canceled | The Merchant Installment was canceled. |
| Voided | The Merchant Installment was voided. |

### The Merchant Installment Logs

Every time a Merchant Installment changes, we create a Log. Logs are useful for understanding the life cycle of each installment. Whenever a new Log is created, we'll send a webhook to your registered URL.

Check out this diagram to understand the possible Merchant Installment Logs:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Merchant Installment was created in Stark Bank. |
| Paid | Paid | The Merchant Installment was paid to your account. |
| Canceled | Canceled | The Merchant Installment was canceled. |
| Voided | Voided | The Merchant Installment was voided. |

Note: You only receive these webhooks if you have the merchant-installment subscription set.

### Querying Merchant Installments

You can retrieve a Merchant Installment by its ID or even list them using parameters such as limit, after, before to filter the results, as shown in the example below:

### Querying Merchant Installment Logs

You can retrieve Merchant Installment Logs by using parameters such as limit, after, before to filter the results, as shown in the example below:

Each log tracks a status change in the installment's life cycle.

### Receiving Installment Webhook

Listen to Merchant Installment Webhooks

After creation, you can use asynchronous Webhooks to monitor status changes of the entity. The Merchant Installment follows this life cycle:

Every time a Merchant Installment changes, we create a Log. Logs are useful for understanding the life cycle of each Merchant Installment. Whenever a new Log is created, we'll send a webhook to your registered URL.

---

## Other Languages

- [Python](https://docs.starkbank.com/get-started/card-payment-python.md)
- [Node.js](https://docs.starkbank.com/get-started/card-payment-node.md)
- [PHP](https://docs.starkbank.com/get-started/card-payment-php.md)
- [Java](https://docs.starkbank.com/get-started/card-payment-java.md)
- [Ruby](https://docs.starkbank.com/get-started/card-payment-ruby.md)
- [Elixir](https://docs.starkbank.com/get-started/card-payment-elixir.md)
- [.NET](https://docs.starkbank.com/get-started/card-payment-dotnet.md)
- [Go](https://docs.starkbank.com/get-started/card-payment-go.md)
- [Clojure](https://docs.starkbank.com/get-started/card-payment-clojure.md)
- [cURL](https://docs.starkbank.com/get-started/card-payment-curl.md)