# 3.1. HTTP Request transaction API

### Example URL to send the POST request to

```
https://api.axepta.pl/v1/merchant/6yt3gjtm9p7b8h9xsdqz/transaction
```

### Request payload

```json
{
    "type": "sale",
    "serviceId": "62f574ed-d4ad-4a7e-9981-89ed7284aaba",
    "amount": 9900,
    "currency": "PLN",
    "orderId": "12",
    "clientIp": "192.168.10.2",
    "paymentMethod": "pbl",
    "paymentMethodChannel": "bnpparibas",
    "successReturnUrl": "https://domain.com/success",
    "failureReturnUrl": "https://domain.com/failure",
    "customer": {
        "firstName": "Maciej",
        "lastName": "Kowalski",
        "email": "jan.kowalski@example.com"
    }
}
```

### Payload parameters

| Parameter            | Type                  | Required | Description |
|---------------------|-----------------------|----------|-------------|
| `type`              | string                | ✔️       | Transaction type. <br>**Allowed values**: `sale`. |
| `serviceId`         | string(36)            | ✔️       | Store identifier as UUID v4. |
| `clientIp`          | string                | ✔️       | Client IP address in IPv4 or IPv6 format. |
| `amount`            | integer(1-999999999)  | ✔️       | Transaction amount in the smallest currency unit, e.g. grosz. |
| `currency`          | string(3)             | ✔️       | Transaction currency in ISO 4217 format. |
| `orderId`           | string(100)           | ✔️       | Merchant order number; <br> **allowed characters**: A-Za-z0-9#_-.\/ plus space (0x20) and UNICODE range 00C0 - 02C0. |
| `title`             | string(255)           | -        | Transaction title; <br> **allowed characters**: A-Za-z0-9#&_-"',.\/ plus space (0x20) and UNICODE range 00C0 - 02C0. |
| `paymentMethod`     | string                | ✔️       | Order processing method. More information in section [1.4 Transaction methods and channels]. |
| `paymentMethodChannel` | string             | ✔️       | Payment channel. More information in section [1.4 Transaction methods and channels]. |
| `successReturnUrl`  | string(300)           | ✔️       | Return URL after successful payment. |
| `failureReturnUrl`  | string(300)           | ✔️       | Return URL in case of payment error. |
| `returnUrl`         | string(300)           | ✔️       | Default return URL. |
| `customer`          | object                | ✔️       | Customer data. |
| `billing`           | object                | -        | Payer data. |
| `shipping`          | object                | -        | Delivery data. |
| `card`              | object                | -        | Card payment data. (Required for `card` payments) |
| `additionalData`    | object                | -        | Payer browser information required for card payments with 3DS authorization. |
| `activeTo`          | integer, null         | -        | Transaction expiration date as Unix timestamp (seconds). If not provided or null, transaction is valid indefinitely. |
| `distributor`       | string                | -        | Distributor name, allowed value: "shoper". |
| `surcharge`         | boolean               | -        | Flag determining whether payer charging will be used for the transaction. Allowed values: 'true', 'false' (requires onboarding setting). |
| `blikCode`          | integer(6)            | -        | BLIK code value for transactions where the code is provided via API. |

> If the request contains `billing`, `shipping` or `card`, additional parameters described below are required.

<br></br>

#### customer

| Parameter    | Type         | Required | Description |
|-------------|--------------|----------|-------------|
| `firstName` | string(100)  | ✔️       | Customer first name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters)|
| `lastName`  | string(100)  | ✔️       | Customer last name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `cid`       | string(36)   | -        | Customer/payer identifier assigned by merchant; allowed characters: A-Za-z0-9 and hyphen (0x2D). |
| `phone`     | string(20)   | -        | Phone number; allowed characters: 0-9+- and space (0x20). |
| `email`     | string(200)  | ✔️       | Email address. |
| `locale`    | string(2)    | -        | Payer locale; determines email language; **allowed values**: `pl`, `en`. |

The default email language is Polish for PLN transactions and English for other currencies.

#### billing

| Parameter            | Type         | Required | Description |
|---------------------|--------------|----------|-------------|
| `firstName`         | string(100)  | ✔️       | First name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `lastName`          | string(100)  | ✔️       | Last name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `company`           | string(200)  | -        | Company name; allowed characters: A-Za-z0-9-"'/,. plus space and UNICODE 00C0 - 02C0 (including Polish diacritical characters)|
| `street`            | string(200)  | -        | Street; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `city`              | string(100)  | -        | City; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `region`            | string(100)  | -        | Region; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `postalCode`        | string(30)   | -        | Postal code; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `countryCodeAlpha2` | string(2)    | -        | Country code Alpha2. |

#### shipping

| Parameter            | Type         | Required | Description |
|---------------------|--------------|----------|-------------|
| `firstName`         | string(100)  | ✔️       | First name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `lastName`          | string(100)  | ✔️       | Last name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `company`           | string(200)  | -        | Company name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters). |
| `street`            | string(200)  | -        | Street; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `city`              | string(100)  | -        | City; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `region`            | string(100)  | -        | Region; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `postalCode`        | string(30)   | -        | Postal code; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `countryCodeAlpha2` | string(2)    | -        | Country code Alpha2. |

#### card

| Parameter   | Type        | Required | Description |
|------------|-------------|----------|-------------|
| `firstName`| string(100) | ✔️       | Cardholder first name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `lastName` | string(100) | ✔️       | Cardholder last name; allowed characters: A-Za-z0-9#&_-"',.\/ plus space(0x20) and characters from UNICODE 00C0 - 02C0 (including Polish diacritical characters) |
| `number`   | string(16)  | ✔️       | Card number |
| `month`    | string(2)   | ✔️       | Expiry month |
| `year`     | string(4)   | ✔️       | Expiry year |
| `cvv`      | string(4)   | ✔️       | CVV code |