# Merchant Integration Guide

This Merchant Integration guide walks you through the steps to start accepting payments quickly and securely using Paypercut.  
Whether you want a fully customized checkout experience, a checkout page, or a plug-and-play solution  
for your website or e-commerce platform, we’ve got you covered.  
By the end of this guide, you will be able to:

* Onboard your business  
* Choose the right integration method for your needs  
* Start accepting payments securely  
* Handle webhooks, errors, and transaction scenarios effectively  
* Configure payouts  
* Complete the go-live checklist

## Merchant Onboarding

To activate payments, your business must first complete the onboarding process:

1. Log in to the [Merchant Dashboard](https://dashboard.paypercut.io/) with your credentials.  
2. You will be directed to start filling in your business details.  
3. Provide required business and financial information.  
4. Submit verification documents (as requested).

### Regional coverage

Regional coverage: Paypercut currently supports merchant onboarding for businesses registered in the EU and EEA.
Supported currencies: Paypercut supports multiple currencies including EUR, USD, GBP, and others. See [Supported currencies](./supported-currencies.md).

## Obtain API Keys

1. Log in to your [Merchant Dashboard](https://dashboard.paypercut.io/).  
2. Go to API Keys → Create New API keys.  
3. There are two different types of keys based on your account (sandbox, production):  
   * Sandbox API Key – for testing.  
   * Production API Key – for live transactions (requires merchant onboarding).

Store your keys securely. Do not expose production keys in frontend code.

## Environment URLs

When integrating with the Paypercut API, you'll work with two environments:

* A staging environment for application development and testing purposes.  
* A production environment for live operations.

| Environment | Base URL |
| :---- | :---- |
| Production | [https://api.paypercut.io](https://api.paypercut.io/) |

## Authentication

All API calls require API key authentication.

* Use sandbox keys in testing.  
* Switch to production keys when ready to go live.  
* Detailed request formats can be found in the [API Reference](https://docs.paypercut.io/api-reference).

## Choose Your Integration Method

| Integration Method | Description | Setup Required | Best For |
| :---- | :---- | :---- | :---- |
| Direct API Integration | Connect your backend directly to Paypercut APIs | API keys, backend development, webhooks | Custom checkout, full control over payment flow |
| Checkout | Paypercut checkout page embedded in your site or as a redirect | Copy JS snippet or redirect | Fast setup, minimal development, PCI-light solution |
| Plugins / Extensions | Ready-made plugins for CMS/e-commerce platforms (Shopify, WooCommerce, Magento, etc.) | Install plugin, enter API keys | Plug-and-play, minimal technical effort, quick go-live |

## API Reference & Requests

For detailed request formats, payloads, and examples, see the [API Reference](https://docs.paypercut.io/api-reference).

## Payment Profiles

A payment profile defines which payment methods your merchant account can use. Each merchant needs  
at least one payment profile.

### Required Information

* Accepted payment methods (card, banking, wallets)  
* Capture mode for card payments: Manual or Instant

### Card Payment Configuration

| Option | Description |
| :---- | :---- |
| Payment Contract Type | One-off (single payment), Recurring (subscriptions) |
| Card Auth Type | Pre-auth (reserve funds), Final-auth (capture full amount), Account status check (validate card for future use) |
| Capture Mode | Instant (auto-capture), Manual (capture later) |
| Wallet Types | Google Pay, Apple Pay |
| 3D Secure | Frictionless or challenge flow |

### Statement Descriptor

The statement descriptor appears on cardholder statements.

* Can be set per payment profile using the Dynamic Descriptor field  
* Must be 5–18 characters, only Latin alphanumeric and spaces

## Webhooks & Event Handling

You can configure webhook endpoints via the API to be notified about events that happen in your Paypercut account.

* Listen to events for real-time updates.  
* Full webhook payloads and validation are described in the [API Reference](https://docs.paypercut.io/api-reference).

## Test Payments & Error Handling

:::scalar-callout{type="danger"}
Do not use any real card data in the sandbox environment. You should only use the following 
testing cards provided by Paypercut.
:::

You can use the following card numbers to execute test transaction scenarios.

| Card Number         | Card Brand          | Scenario |
|:--------------------|:--------------------|:---------|
| `5204 2477 5000 1471` | MASTERCARD | Successful Frictionless Authentication         |
| `4000 0200 0000 0000` | VISA | Successful Frictionless Authentication         |
| `4005 5622 3121 2123` | VISA | Successful Challenge Authentication - Method not Required	         |
| `4761 3699 8032 0253` | VISA | Successful Mandated Challenge Authentication	         |
| `4000 0000 0000 0341` | VISA | Successful Out-of-Band Challenge Authentication	         |
| `4005 5717 0111 1111` | VISA | Attempted Challenge Authentication	         |
| `4111 1111 1111 1111` | VISA | Authentication Attempted	         |
| `4264 2815 1111 2228` | VISA | Authentication Failed	         |
| `5405 0011 1111 1165` | MASTERCARD | Authentication Unavailable	         |
| `4055 0111 1111 1111` | VISA | Failed Challenge Authentication	         |
| `4264 2815 0000 3339` | VISA | 3DS Directory Server Error	         |
| `4264 2815 0000 1119` | VISA | Internal 3DS Server Error	         |
| `4200 0000 0000 0002` | VISA | Successful Frictionless Authentication	         |
| `4200 0000 0000 0004` | VISA | Successful Challenge Authentication	         |
| `4200 0000 0000 0014` | VISA | Successful Challenge Authentication - Method not Required	         |
| `4200 0000 0000 0015` | VISA | Successful Mandated Challenge Authentication	         |
| `4200 0000 0000 0006` | VISA | Authentication Unavailable	         |
| `4200 0000 0000 0007` | VISA | Authentication Rejected	         |

All test cards work with any future expiry date and any CVV.  
Use idempotency keys to prevent duplicate charges.  
Detailed error messages and codes are in the [API Reference](https://docs.paypercut.io/api-reference).

## Payouts

Merchants receive payouts to their linked bank account, scheduled as agreed during the onboarding process (daily, weekly, monthly).

| Frequency | Description |
| :---- | :---- |
| Daily | All cleared funds are transferred daily |
| Weekly | Aggregated payouts once per week |
| Monthly | Monthly settlements |

## Going Live Checklist

Before going live, make sure you’ve completed the following steps:

* Completed your onboarding  
* Configured at least one payment profile  
  * Enabled card payments (if applicable)  
  * Set up the correct transaction types  
* Confirm integration completeness by:  
  * Updating all API endpoints from sandbox to production URLs  
  * Implementing error handling  
  * Configuring webhook handling  
  * Testing success and failure flows  
  * Replacing sandbox keys with production keys  
  * Enabling production webhooks  
  * Performing a small test transaction in production and verifying the complete flow  
* Confirmed your bank account details for payouts