# PrimeiroPay

The PrimeiroPay Platform is a single unified RESTful API allowing access to the complete set of the Open Payment Platform features and frontend widgets. Choose an option below to get started.


# Getting Started

[**Server To Server API** ](https://primeiro-pay.gitbook.io/primeiro-pay/getting-started/server-to-server-api)

{% hint style="info" %}
This integration variant requires you have a PCI-Compliance certify to collect the card data, if you chose this option you will increase your PCI-compliance scope.
{% endhint %}

[**Hosted Checkout**](https://primeiro-pay.gitbook.io/primeiro-pay/getting-started/hosted-checkout)

{% hint style="info" %}
If you don't have a PCI-Compliance certify or want to minimize your PCI-compliance requirements, we recommend that you use a Non PCI Complience integration.
{% endhint %}


# Server To Server API


# Preauthorization Card

 A PA is created by sending a POST request over HTTPS to the `/v1/payments` resource. The request should include all required information such as your authentication credentials, the type of transaction, the amount and the payment information such as card details. A capture may be sent against a successful PA to request that the funds are sent for clearing.

{% hint style="info" %}
This method is only used in Brazil at the moment
{% endhint %}

Example:

```
curl https://test.oppwa.com/v1/payments \
 -d "entityId=8ac7a4ca6db97ef1016dbe9214e70aac" \
 -d "amount=100.00" \
 -d "currency=BRL" \
 -d "paymentBrand=VISA" \
 -d "paymentType=DB" \
 -d "card.number=4200000000000000" \
 -d "card.holder=Jane Jones" \
 -d "card.expiryMonth=05" \
 -d "card.expiryYear=2020" \
 -d "card.cvv=123" \
 -d "testMode=EXTERNAL" \ Test Evroment Only
 -H "Authorization: Bearer OGFjN2E0Y2E2ZGI5N2VmMTAxNmRiZTkwZTMxZDBhYTh8WENkRUs0NHJubQ=="
```

{% file src="/files/-MGhhGxB2IkijCUj53ds" %}
Preauthorization Card Json Request
{% endfile %}


# Capture

 A capture is used to request clearing for previously authorized funds.  A capture request is performed against a previous preauthorization (PA) payment by referencing its `payment.id` and sending a POST request over HTTPS to the /payments/{id} endpoint.  Captures can be for full or partial amounts and multiple capture requests against the same PA are allowed.

(This method is only used in Brazil at the moment)

Example:

```
curl https://test.oppwa.com/v1/payments/{id} \
 -d "entityId=8a8294184e736012014e78a17a5615ac" \
 -d "amount=10.00" \
 -d "currency=EUR" \
 -d "paymentType=CP" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

{% file src="/files/-MGhhB3nqBo3Hg48PhZ4" %}
Capture Json Request
{% endfile %}


# Debit

 A DB is created by sending a POST request over HTTPS to the `/v1/payments` resource. The request should include all required information such as your authentication credentials, the type of transaction, the amount and the payment information such as card details. A DB request effectively combines a PA and capture request, automatically requesting that the funds are cleared if the authorization was successful.

{% hint style="info" %}
You can use this method to generate transactions in Brazil, Mexico and Colombia.

For transactions in Brazil use currency: BRL, for Mexico: MXN and for Colombia: COL
{% endhint %}

Example:

```
curl https://test.oppwa.com/v1/payments \
 -d "entityId=8a8294184e736012014e78a17a5615ac" \
 -d "amount=92.00" \
 -d "currency=BRL" \
 -d "paymentBrand=VISA" \
 -d "paymentType=DB" \
 -d "card.number=4200000000000000" \
 -d "card.holder=Jane Jones" \
 -d "card.expiryMonth=05" \
 -d "card.expiryYear=2034" \
 -d "card.cvv=123" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

{% file src="/files/-MGhh5G4ROTk3Qa6e3s7" %}
Debit Json Request
{% endfile %}


# Refund

 A refund is performed against a previous payment, referencing its `payment.id` by sending a POST request over HTTPS to the /payments/{id} endpoint. A refund can be performed against debit (DB) or captured preauthorization (PA->CP) payment types. Where supported, the amount field can be used to process a partial or full amount.

Example:

```
curl https://test.oppwa.com/v1/payments/{Payment ID} \
 -d "entityId=8ac7a4ca6db97ef1016dbe9214e70aac" \
 -d "amount=10.00" \
 -d "currency=BRL" \
 -d "paymentType=RF" \
 -d "testMode=EXTERNAL" \ Test Evroment Only
 -H "Authorization: Bearer OGFjN2E0Y2E2ZGI5N2VmMTAxNmRiZTkwZTMxZDBhYTh8WENkRUs0NHJubQ=="
```

{% file src="/files/-MGhgzLe5sje0i-KSDQs" %}
Refund Json Request
{% endfile %}


# Reversal

 A reversal is performed against a previous payment, referencing its `payment.id` by sending a POST request over HTTPS to the /payments/{id} endpoint. A reversal can be sent against debit (DB) or preauthorization (PA) payment types. When reversing a card payment and if sent within 72 hours of the original request, a reversal causes an authorization reversal request to be sent the card issuer to clear the funds held against the authorization.

Example:

```
curl https://test.oppwa.com/v1/payments/{Payment ID} \
 -d "entityId=8ac7a4ca6db97ef1016dbe9214e70aac" \
 -d "paymentType=RV" \
 -d "testMode=EXTERNAL" \ Test Evroment Only
 -H "Authorization: Bearer OGFjN2E0Y2E2ZGI5N2VmMTAxNmRiZTkwZTMxZDBhYTh8WENkRUs0NHJubQ=="
```

{% file src="/files/-MGhgs8RMytpsrPUGOmu" %}
Reversal Json Request
{% endfile %}


# Schedule a Payment

With Scheduling API, you can schedule DB, PA or CD transaction in the future.

### How it works

### 1. Store the payment data

Register the customer payment information could be done from [PrimeiroPay](https://developers.primeiropay.com/tokenization) or could be done through Server-To-Server in two methods: [Store the data during a payment](https://primeiropay.docs.oppwa.com/tutorials/server-to-server/tokenisation#during-payment) or [store it as stand alone.](https://primeiropay.docs.oppwa.com/tutorials/server-to-server/tokenisation#stand-alone)

Following is an example of stand alone registration.

```
curl https://test.oppwa.com/v1/registrations \
 -d "entityId=8a8294184e736012014e78a1b1da15d3" \
 -d "paymentBrand=VISA" \
 -d "card.number=4200000000000000" \
 -d "card.holder=Jane Jones" \
 -d "card.expiryMonth=05" \
 -d "card.expiryYear=2021" \
 -d "card.cvv=123" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

Try it Out

### 2. Schedule a payment

Send a request to /schedules end point with the registrationId, payment type and the job schedule which describes when and how often the transaction should be committed.

For complete reference of job parameters, check [API Parameters Reference:](https://primeiro-pay.gitbook.io/primeiro-pay/api-parameters-reference)

```
curl https://test.oppwa.com/scheduling/v1/schedules \
 -d "entityId=8a8294184e736012014e78a1b1da15d3" \
 -d "registrationId={registrationId}" \
 -d "amount=17.00" \
 -d "currency=EUR" \
 -d "paymentType=DB" \
 -d "job.month=*" \
 -d "job.dayOfMonth=1" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

Try it Out

### 3. We execute the transaction for you

As the scheduled transaction triggers, the system commits the payment transaction on time using the stored payment information and payment type specified.

The system will commit a payment transaction with the paymentType, amount and currency specified, and will use the payment information registered on the first step.

### 4. Cancel the schedule

As the case of canceling the scheduled transaction, merchant sends a deschedule request to cancel future transactions.

Send a request to the de-scheduling specifying the **referenceId** of the scheduled transaction as following:

```
Curl https://test.oppwa.com/scheduling/v1/schedules/{id}
 -X DELETE "https://test.oppwa.com/scheduling/v1/schedules/{id}\?entityId=8a8294184e736012014e78a1b1da15d3" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```


# Recurring

You can perform recurring payments by just adding one additional parameter, `recurringType`, to the payment request.

A recurring workflow consists of two phases:

1. The initial payment request
2. Subsequent payment requests

[Initial Payment](https://developers.primeiropay.com/getting-started/server-to-server-api/recurring-1/initial-payment)

[Repeated Payment](https://developers.primeiropay.com/getting-started/server-to-server-api/recurring-1/repeated-payment)

[Schedule a Payment](https://primeiro-pay.gitbook.io/primeiro-pay/getting-started/pci-complience/recurring-1/untitled-1-1)

####

####


# Initial Payment

#### Sending the Initial Payment

During the initial payment, marked by the parameter `recurringType` with the value `INITIAL`, the customer is present. Therefore this initial request should contain additional parameters that authenticate the customer like `card.cvv` for card payments, and also additional checks like 3D secure can be executed.

In **Primeiro Pay** you get this behaviour out of the box, so all you have to do is to follow the [Primeiro Pay Integration guide](https://developers.primeiropay.com/getting-started/hosted-checkout/copy-and-pay-1) and add to the /checkouts request in [step 1](https://primeiropay.docs.oppwa.com/integration-guide#CNPStep1) this parameter:

| recurringType=INITIAL |   |
| --------------------- | - |

```
curl https://test.oppwa.com/v1/payments \
 -d "entityId=8a8294184e736012014e78a17a5615ac" \
 -d "amount=92.00" \
 -d "currency=EUR" \
 -d "paymentBrand=VISA" \
 -d "paymentType=DB" \
 -d "card.number=4200000000000000" \
 -d "card.holder=Jane Jones" \
 -d "card.expiryMonth=05" \
 -d "card.expiryYear=2034" \
 -d "card.cvv=123" \
 -d "recurringType=INITIAL" \
 -d "createRegistration=true" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

For some cases you might want to use an alternative approach: If the shopper just registered his data without sending a payment at the same time you would have sent his payment directly to the /registrations endpoint as [described here](https://primeiropay.docs.oppwa.com/tokenisation#stand-alone). In the same way as described above, the `recurringType=INITIAL` parameter can be added to the request to indicate that this is the first in a series of recurring payments.

You can find more details on the server-to-server option using either /payments or /registrations in the the [tokenisation tutorial.](https://primeiropay.docs.oppwa.com/tutorials/manage-payments/recurring?q=tokenisation)

{% file src="/files/-MGjyfcwooA5iP4IzNQh" %}
Initial Payment Json Request
{% endfile %}


# Repeated Payment

#### Sending a repeated payment

Any payment request following the initial one has to have the parameter `recurringType` with the value `REPEATED`. This flag not only indicates that the request is part of a series of payments on this account, but also tells the payment system that no user is present and therefore parameters like `card.cvv` or the 3D authentication shouldn't be present. This fact in combination with the stored payment data of the registration greatly reduces the number of parameters of such a request:

```
https://test.oppwa.com/v1/registrations/{registrationId}/payments⠀⠀
```

```
curl https://test.oppwa.com/v1/registrations/{registrationId}/payments \
 -d "entityId=8a8294184e736012014e78a17a5615ac" \
 -d "amount=92.00" \
 -d "currency=EUR" \
 -d "paymentType=PA" \
 -d "recurringType=REPEATED" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

{% file src="/files/-MGjysLYYMK-JX0F\_dHW" %}
Recurring Repeated Json Request
{% endfile %}


# Tax Identification Number

CPF

 **The collection of the CPF (Tax Identification number) is mandatory for all payments in Brazil.**

**You have to use these parameters in your request:**

```
-d "customer.identificationDocType=TAXSTATEMENT" \
-d "customer.identificationDocId=70383053102" \
```

Example:

```
curl https://test.oppwa.com/v1/payments \
 -d "entityId=8ac7a4ca6db97ef1016dbe9214e70aac" \
 -d "amount=100.00" \
 -d "currency=BRL" \
 -d "paymentBrand=VISA" \
 -d "paymentType=DB" \
 -d "card.number=4200000000000000" \
 -d "card.holder=Jane Jones" \
 -d "card.expiryMonth=05" \
 -d "card.expiryYear=2020" \
 -d "card.cvv=123" \
 -d "customer.identificationDocType=TAXSTATEMENT" \
 -d "customer.identificationDocId=70383053102" \
 -d "testMode=EXTERNAL" \ Test Evroment Only
 -H "Authorization: Bearer OGFjN2E0Y2E2ZGI5N2VmMTAxNmRiZTkwZTMxZDBhYTh8WENkRUs0NHJubQ=="
```


# Hosted Checkout


# Copy and Pay

### 1. Prepare the checkout

First, perform a server-to-server POST request to prepare the checkout with the required data, including the order type, amount and currency. The response to a successful request is a JSON string with an `id`, which is required in the second step to create the payment form.

```
curl https://test.oppwa.com/v1/checkouts \
 -d "entityId=8a8294184e736012014e78a17a5615ac" \
 -d "amount=92.00" \
 -d "currency=EUR" \
 -d "paymentType=DB" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

 For a full list of parameters that can be sent in the prepare checkout request, please see the [API Reference](https://primeiro-pay.gitbook.io/primeiro-pay/api-parameters-reference)

{% hint style="info" %}
Please note that for a HTTP POST request all the parameters are expected to go into the message body and not into the URL.
{% endhint %}

### 2. Create the payment form

To create the payment form you just need to add the following lines of HTML/JavaScript to your page and populating the following variables

* The checkout's `id` that you got in the response from step 1

```
<script src="https://test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>
```

&#x20;The `shopperResultUrl`, which is the page on your site where the customer should be redirected to after the payment is processed and the brands that will be available.

```
<form action="{shopperResultUrl}" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>
```

&#x20;View the [customization guide](https://primeiropay.docs.oppwa.com/tutorials/integration-guide/customisation) for more information on customizing the payment form.

{% hint style="info" %}
A checkout id expires when a payment has been finalized successfully by user, but not later than 30 minutes. Before it expires, it can be used multiple times in order to retrieve a valid payment form. This can occur for example when a user does not finish a payment and reloads the page, or uses the back button of the browser. Therefore you don't have to generate a new checkout ID in such scenarios. However be aware that such cases can generate multiple transactions in the system, for example one (or more) failed and another one successful, based on the same checkout id.
{% endhint %}

### 3. Get the payment status <a href="#getstatus" id="getstatus"></a>

Once the payment has been processed, the customer is redirected to your `shopperResultUrl` along with a GET parameter `resourcePath`.

**Important**: The baseUrl must end in a "/", e.g. "<https://test.oppwa.com/>".

Then, to get the status of the payment, you should make a GET request to the `baseUrl + resourcePath`, including your authentication parameters.

Example of a resourcePath:

```
resourcePath=/v1/checkouts/{checkoutId}/payment
```

&#x20;Once a status response is successful the checkout identifier can't be used anymore. In this case the [Transaction Reports](https://primeiropay.docs.oppwa.com/tutorials/reporting/transaction) endpoint can be used to get the transaction status using the payment id.

```
curl -G https://test.oppwa.com/v1/checkouts/{id}/payment \
 -d "entityId=8a8294184e736012014e78a17a5615ac" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

IMPORTANT: A throttling rule applies for get payment status calls. Per checkout, it is allowed to send two get payment requests in a minute.

We recommend that you verify the following fields from the Payment Status response, by comparing the returned values with expected:

* ID(s)
* Amount
* Currency
* Brand
* Type


# Customization

You can customize the look and feel of the PrimeiroPay payment form using the options below.

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MGjmO_bSsf-ecWdA1dv%2F-MGjoClmulpUEEXyai2y%2Fimage.png?alt=media\&token=9538e797-160b-46c8-bbb3-3fba638f81f5)

html

```
<form action="https://primeiropay.docs.oppwa.com/tutorials/integration-guide/customisation" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>
```

css

```
body {background-color:#f6f6f5;}
```

js

```
var wpwlOptions = {style:"card"}
```

[Click here for Mozilla's CSS reference guide](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference)

### Style Options

The style of the payment form can be changed by setting the **style** option in the wpwlOption object before the payment widget is loaded. Valid options are:

* plain
* card

```
<script>
    var wpwlOptions = {
        style: "card"
    }
</script>
<script async src="https://test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>
```

#### Card Number and CVV placeholder styles

In order to change the style of the placeholders inside card-number and cvv, please use the option iframeStyle, according to the example below:

```
<script>
var wpwlOptions = {
    iframeStyles: {
        'card-number-placeholder': {
            'color': '#ff0000',
            'font-size': '16px',
            'font-family': 'monospace'
        },
            'cvv-placeholder': {
            'color': '#0000ff',
                'font-size': '16px',
                'font-family': 'Arial'
        }
    }
}</script>
<script async src="https://test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>
```

(Please note that only Web Safe fonts are supported)

### Language Options

The language of the labels on the payment form can be changed by setting the **locale** option in the wpwlOption object before the payment widget is loaded.

```
<script>
    var wpwlOptions = {
        locale: "en"
    }
</script>
<script async src="https://test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>
```

&#x20;Show all supported locales

### Brands Options

Payment options can be selected manually by entering the options in the `<form>` tag.

```
<form action="" class="paymentWidgets" data-brands="VISA MASTER"></form>
```

&#x20;Show all supported brands

### CSS Reference

As you have seen above, you can override any of the form's CSS simply by adding custom CSS in your stylesheet. For advanced style we recommend using a default style of plain, however custom stylesheets can be combined with any of the default style options.

#### Base CSS Classes

For performance reasons, all elements have a base CSS class and individual CSS class, e.g. the credit card payment form container has a base `.wpwl-container` class and an individual `.wpwl-container-card` class to specify the card payment form container.

**Container**

`.wpwl-container` wraps the payment form. Use this to apply, for example, margins between your page elements and the payment form.

```
<div class="wpwl-container">
    ...
</div>
```

Individual classes:

`.wpwl-container-card`

**Form**

`.wpwl-form` styles all payment forms. Use this to change the look and feel of the payment form, including backgrounds or shadows.

```
<form class="wpwl-form wpwl-clearfix" action="https://test.oppwa.com/v1/checkouts/{checkoutId}/payment" method="POST" target="cnpIframe" lang="en">
    ...
</form>
```

Individual classes:

`.wpwl-form-card`

**Groups**

`.wpwl-group` wraps the label and the wrapper of the input element. Use this to style labels and inputs together, i.e. position or width.&#x20;

```
<div class="wpwl-group">
    <div class="wpwl-label">...</div>
    <div class="wpwl-wrapper">...</div>
</div>
```

Individual classes:

`.wpwl-group-brand`&#x20;

`.wpwl-group-cardNumber`&#x20;

`.wpwl-group-expiry`&#x20;

`.wpwl-group-cardHolder`&#x20;

`.wpwl-group-cvv`&#x20;

`.wpwl-group-submit` styles the ""Pay now" button.

`.wpwl-group-button` styles the buttons containing the brand

**Labels**

`.wpwl-label` holds the label of an input element.

```
<div class="wpwl-label">
    Card Number
</div>
```

Individual classes:

`.wpwl-label-brand`

`.wpwl-label-cardNumber`

`.wpwl-label-expiry`

`.wpwl-label-cardHolder`

`.wpwl-label-cvv`

**Input and Select Wrappers**

Input and select elements are wrapped in a div to gain more control over their styles, especially their width.&#x20;

`.wpwl-wrapper` holds an input or select element. Use this to set the width of the containing input or select element.

```
<div class="wpwl-wrapper">
    ...
</div>
```

Individual classes:

`.wpwl-wrapper-brand`&#x20;

`.wpwl-wrapper-cardNumber`&#x20;

`.wpwl-wrapper-expiry`&#x20;

`.wpwl-wrapper-cardHolder`&#x20;

`.wpwl-wrapper-cvv`&#x20;

`.wpwl-wrapper-submit`&#x20;

**Input and Select Elements**

All textual `<input>`, `<textarea>`, and `<select>` elements have a base `.wpwl-control` class and are set to `width: 100%;` by default.  The width of these elements should be set via `.wpwl-wrapper`.

`.wpwl-control` styles the borders, backgrounds or paddings of all `<input>` and `<select>` elements.&#x20;

```
<input class="wpwl-control wpwl-control-cardNumber" name="card.number" autocomplete="off" type="tel" placeholder="Card Number">
```

```
<select class="wpwl-control wpwl-control-brand" name="paymentBrand">
    <option value="MASTER">Mastercard</option>
    <option value="VISA">Visa</option>
</select>
```

Individual classes:

`.wpwl-control-brand`&#x20;

`.wpwl-control-cardNumber`&#x20;

`.wpwl-control-expiry`&#x20;

`.wpwl-control-cardHolder`&#x20;

`.wpwl-control-cvv` &#x20;

**Buttons**

`.wpwl-button` styles the submit buttons.

```
<button type="submit" name="pay" class="wpwl-button wpwl-button-pay">Pay now</button>
```

Individual classes:

`.wpwl-button-pay` styles the "Pay now" button.

`.wpwl-button-brand` styles the buttons containing a brand.

**Brands**

`.wpwl-brand` styles the brand icons.

```
<div class="wpwl-brand wpwl-brand-MASTER"></div>
```

Individual classes:

`.wpwl-brand-card` styles the card brands

`.wpwl-brand-BRAND` styles the specific brand.

**Error Hints**

`.wpwl-has-error` adds a red background, border and color to the input element and a red color to the next `.wpwl-hint` element.

```
<input autocomplete="off" type="tel" name="card.number" class="wpwl-control wpwl-control-cardNumber wpwl-has-error" placeholder="Card Number">
<div class="wpwl-hint wpwl-hint-cardNumberError">
    Invalid card number or brand
</div>
```

Individual classes:

`.wpwl-hint-cardNumberError`

`.wpwl-hint-expiryError`

`.wpwl-hint-cardHolderError`

`.wpwl-hint-cvvError`

**Helpers**

`.wpwl-clearfix` allows elements to contain floats without re-sorting. Assuming that .wpwl-label and .wpwl-wrapper are floated, .wpwl-group needs .wpwl-clearfix.

```
<div class="wpwl-group wpwl-clearfix">
    <div class="wpwl-label">...</div>
    <div class="wpwl-wrapper">...</div>
</div>
```

#### Credit Card HTML and CSS Classes

Here is an example HTML output of the credit card payment form:

```
<div id="card_220921339056" class="wpwl-container wpwl-container-card">
    <form class="wpwl-form wpwl-form-card wpwl-clearfix" action="https://test.oppwa.com/v1/checkouts/{checkoutId}/payment" method="POST" target="cnpIframe" lang="en">
        <div class="wpwl-group wpwl-group-brand wpwl-clearfix">
            <div class="wpwl-label wpwl-label-brand">Brand</div>
            <div class="wpwl-wrapper wpwl-wrapper-brand">
                <select class="wpwl-control wpwl-control-brand" name="paymentBrand">
                    <option value="MASTER">Mastercard</option>
                    <option value="VISA">Visa</option>
                </select>
            </div>
            <div class="wpwl-brand wpwl-brand-card wpwl-brand-MASTER"></div>
        </div>
        <div class="wpwl-group wpwl-group-cardNumber wpwl-clearfix">
            <div class="wpwl-label wpwl-label-cardNumber">Card Number</div>
            <div class="wpwl-wrapper wpwl-wrapper-cardNumber">
                <input autocomplete="off" type="tel" name="card.number" class="wpwl-control wpwl-control-cardNumber" placeholder="Card Number">
            </div>a
        </div>
        <div class="wpwl-group wpwl-group-expiry wpwl-clearfix">
            <div class="wpwl-label wpwl-label-expiry">Expiry Date</div>
            <div class="wpwl-wrapper wpwl-wrapper-expiry">
                <input autocomplete="off" type="tel" name="card.expiry"b class="wpwl-control wpwl-control-expiry" placeholder="MM / YY">
            </div>
        </div>
        <div class="wpwl-group wpwl-group-cardHolder wpwl-clearfix">
            <div class="wpwl-label wpwl-label-cardHolder">Card holder</div>
            <div class="wpwl-wrapper wpwl-wrapper-cardHolder">
                <input autocomplete="off" type="text" name="card.holder" class="wpwl-control wpwl-control-cardHolder" placeholder="Card holder">
            </div>
        </div>
        <div class="wpwl-group wpwl-group-cvv wpwl-clearfix">
            <div class="wpwl-label wpwl-label-cvv">CVV</div>
            <div class="wpwl-wrapper wpwl-wrapper-cvv">
                <input autocomplete="off" type="tel" name="card.cvv" class="wpwl-control wpwl-control-cvv" placeholder="CVV">
            </div>
        </div>
        <div class="wpwl-group wpwl-group-submit wpwl-clearfix">
            <div class="wpwl-wrapper wpwl-wrapper-submit">
                <button type="submit" name="pay" class="wpwl-button wpwl-button-pay">Pay now</button>
            </div>
        </div>
        <input type="hidden" name="shopperResultUrl" value="https://test.oppwa.com/v1/checkouts/{checkoutId}/payment">
        <input type="hidden" name="card.expiryMonth" value="">
        <input type="hidden" name="card.expiryYear" value="">
    </form>
</div>
```


# Advanced Options

## Advanced Options

Here you can find some examples of advanced workflow customization for PrimeiroPay. Each of the examples provided use the `wpwlOptions` variable, the full reference for which can be found on our [PrimeiroPay API Reference](https://primeiropay.docs.oppwa.com/widget-api).

Please note that JavaScript examples from PrimeiroPay can be used only when including jQuery.

```
<script src="https://code.jquery.com/jquery.js" type="text/javascript"></script>
```

### Have card holder mandatory

By default the card holder is optional. Some integrations would like to have it mandatory. In order to achieve this we can implement the check on the onBeforeSubmitCard event, like below:

1. Prepare the checkout
2. Using the wpwlOptions API onBeforeCardSubmit event, check if the holder contains 2 or more characters.

\
html

```
<form action="https://primeiropay.docs.oppwa.com/tutorials/integration-guide/advanced-options" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>
```

css

```
body {background-color:#f6f6f5;}
```

js

```
var wpwlOptions = {
  style:"card", 
  onReady: function(e){
    $('.wpwl-form-card').find('.wpwl-button-pay').on('click', function(e){
      validateHolder(e);
    });
  },
  onBeforeSubmitCard: function(e){
    return validateHolder(e);
  }
}
function validateHolder(e){
  var holder = $('.wpwl-control-cardHolder').val();
  if (holder.trim().length < 2){
    $('.wpwl-control-cardHolder').addClass('wpwl-has-error').after('<div class="wpwl-hint wpwl-hint-cardHolderError">Invalid card holder</div>');
    return false;
  }
  return true;
}
```

Result

### Add custom fields

You can add additional parameters to the payment form using the `wpwlOptions` variable, prior to loading Primeiro Pay. In the example above, we add a custom parameter to the payment form for recording the number of installments requested by the customer. The steps are listed below.

1. Prepare the checkout
2. Using the wpwlOptions API onLoad event, add the custom field HTML to the payment form
3. Set the name of the html input field to your API parameter e.g. recurring.numberOfInstallments

html

```
<form action="https://primeiropay.docs.oppwa.com/tutorials/integration-guide/advanced-options" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>
```

css

```
body {background-color:#f6f6f5;}
```

js

```
  var wpwlOptions = {
      style: "card",
          onReady: function() {
            var numberOfInstallmentsHtml = '<div class="wpwl-label wpwl-label-custom" style="display:inline-block">Number of Installments</div>' +
              '<div class="wpwl-wrapper wpwl-wrapper-custom" style="display:inline-block">' +
              '<select name="recurring.numberOfInstallments"><option value="1">1</option><option value="3">3</option><option value="5">5</option></select>' +
              '</div>'; 
            $('form.wpwl-form-card').find('.wpwl-button').before(numberOfInstallmentsHtml);
          }
    }
```

Result

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MGjmO_bSsf-ecWdA1dv%2F-MGjnOx9aEhf1j0aCvVv%2Fimage.png?alt=media\&token=581cd2a7-0f05-42d6-8e97-88cd1b95507f)

### Change label

You can change a label in the payment form using the `wpwlOptions` variable, prior to loading the Primeiro Pay payment widget. In the following example, we'll change the credit card brand label in the payment form.

1. Prepare the order
2. Using the wpwlOptions API onLoad event, use a JQuery selector to set the desired value of the label

html

```
<form action="https://primeiropay.docs.oppwa.com/tutorials/integration-guide/advanced-options" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>
```

css

```
body {background-color:#f6f6f5;}
```

js

```
  var wpwlOptions = {
    onReady: function() {
      $('.wpwl-label-brand').html('Card Brand');  
    }
}

```

Result

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MGjmO_bSsf-ecWdA1dv%2F-MGjnuePcsxwd0F6MRC3%2Fimage.png?alt=media\&token=9cd24bda-f376-4eaf-99bb-903d7ebcabea)


# Getting Start With Adyen

&#x20;Adyen maintains a C-Level integration to us, that means settlement and the related reporting will be directly provided by PrimeiroPay. In order to facilitate this process in the most efficient way, PrimeiroPay offers the same reportings as Adyen does (incl. identical field names and respective values).

**Pre-Requirements:**

* You will need to send us all charges in currency = BRL. See section 7 on how to convert into BRL
* You can either use an existing Merchant Account and configure that all BRL transactions will be routed to PrimeiroPay or you open a separate Merchant Account with Adyen for PrimeiroPay inside Adyen
* An agreement with PrimeiroPay directly. Adyen will be solely the gateway to forward the transaction to us

#### **1. Reporting / Settlement**

Please refer to the following three sections to learn more about PrimeiroPay's reporting and settlement terms. The settlement report provided by PrimeiroPay is **identical** to what you receive from Adyen in other territories. [Reporting Guidelines (external use)](https://primeiro-pay.gitbook.io/primeiro-pay/reporting), [Settlement Term](https://primeiropay.atlassian.net/wiki/spaces/MS/pages/1703950/Settlement+Term), [Connect to PrimeiroPay's SFTP](https://primeiro-pay.gitbook.io/primeiro-pay/connect-to-sftp-1)

#### **2. Chargeback notifications**

Chargebacks are being reported through chargeback reports made available daily through our SFTP. You will also receive them in the settlement report respectively.

To receive chargeback notifications in real-time, please refer to this integration manual to retrieve PrimeiroPay's webhooks:

<https://primeiro-pay.gitbook.io/primeiro-pay/webhook-1>

#### **3. Handling Billing address**

Some payment methods require a billing address to be sent, like Boleto. Please respect the following rules to avoid errors in transactions:

| **Field Name in Adyen**          | **Description**                       | **Format**                                       | **Example** |
| -------------------------------- | ------------------------------------- | ------------------------------------------------ | ----------- |
| billingAddress.country           | Country code with 2 digits            | A2                                               | BR          |
| billingAddress.city              | City                                  | A255                                             | São Paulo   |
| billingAddress.street            | Street                                | AN100 (characters shared with houseNumberOrName) | Av Paulista |
| billingAddress.houseNumberOrName | House Number                          | AN100 (characters shared with Street)            | 1234        |
| billingAddress.stateOrProvince   | State with 2 digits                   | A2                                               | SP          |
| billingAddress.postalCode        | Postal/zip code with 8 numeric digits | N8                                               | 04538905    |

#### **4. Collecting / Sending the CPF number**

PrimeiroPay requires the social security number of the shopper for each transaction. This is required by the Central Bank of Brazil and common practice for any purchase made online.

If you are using the Hosted Payment Page of Adyen, the field can be simply activated there.

If you are using Client Sided Encryption, you will need to send this additional field in your payment request:

| **Field Name in Adyen**      | **Description**                                               | **Format** | **Example**                           |
| ---------------------------- | ------------------------------------------------------------- | ---------- | ------------------------------------- |
| shopper.socialSecurityNumber | CPF number of customer; CNPJ of the company making a purchase | N11 or N14 | 5043991750439917476 or 50966454000190 |

Please validate the CPF number using the following javascript:\
<https://gist.github.com/cauerego/873308>

#### **5. Supported Payment Methods**

| **Adyen Checkout Technology** | **Cards(Visa,Master,Elo,Amex,Hipercard)** | Boletos/Oxxo |
| ----------------------------- | ----------------------------------------- | ------------ |
| Server to Server              | Yes                                       | No           |
| HPP                           | Yes                                       | Yes          |
| Client Sided Encryption       | Yes                                       | No           |
| Adyen checkout API            | Yes                                       | Yes          |

#### **6. Boletos Integration**

When integration boletos it's important to **pay special attention to Billing Fields** restrictions (as billing address is mandatory for Boletos). Please follow all the guidelines contained in the Iten 3 of this guide.

When sending a boleto transaction using Adyen **use the following selected brand**:

**primeiropay\_boleto**

#### **7. Convert your USD prices into BRL**

PrimeiroPay provides a guaranteed FX rate that is valid for the upcoming 24 business hours. This allows you to convert your USD prices into BRL without taking any risk on movements during these 24 hours.

[**Pulling our FX Rates**](https://primeiro-pay.gitbook.io/primeiro-pay/pulling-our-fx-rates-1)


# Cash Based Payments

Cash-Based Payments are popular in Latin America because they can be used even if you didn't have an account bank, this method can be paid with money in an authorized place or online in your cellphone using the bar code.

Once paid, it takes time for the confirmation of the payment (RC), the best way to receive these notifications is by using [Webhook](https://primeiro-pay.gitbook.io/primeiro-pay/webhook-1).

[Boleto](https://primeiro-pay.gitbook.io/primeiro-pay/cash-based-payments/boleto)

[Baloto](https://primeiro-pay.gitbook.io/primeiro-pay/cash-based-payments/baloto)

[Oxxo](https://primeiro-pay.gitbook.io/primeiro-pay/cash-based-payments/oxxo)

[PagoEfectivo](https://primeiro-pay.gitbook.io/primeiro-pay/cash-based-payments/pagoefectivo)

[PIX](https://developers.primeiropay.com/cash-based-payments/pix)


# Boleto

&#x20;A payment slip of a specified amount is issued to the shopper and he can use the bar code in the payment slip to pay for it in his Online Banking, lottery houses, banks and bank correspondents (some small stores, supermarkets, Brazilian post offices, etc).Boleto payments are usually confirmed within 24 hours, however, it depends on when the shopper deposits / pays the Boleto.

Please note that the bank only confirms paid Boletos in weekdays (Monday-Friday). Boletos are also not processed during bank holidays.

**Boleto Bancario is a server to server only payment method to increase conversion**

| Payment Types | Meaning                                                                                                                                              | Success return codes                 |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| PA            | Successful generation of the Boleto. The shopper can go and pay for it online or at any POS such as a bank                                           | 000.000.000 000.100.112 (on staging) |
| RC            | Successful payment of the Boleto. The payment of the Boleto is asynchronous and hence the confirmation will usually come in within 2-3 business days | 000.000.000                          |

#### **Initial Request**

```
//send POST to  [https://test.oppwa.com/v1/payments](https://test.oppwa.com/v1/payments)
//Header -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
amount=10.00
currency=BRL
paymentBrand=BOLETO
paymentType=PA

//API credentials
entityId=8a8294174ae82ada014aedfd75aa1d79 
//API credentials end

//Dummy data, replace with your shopper`s details
billing.street1=Av Brigadeiro Faria Lima 3729
billing.city=Sao Paulo
billing.state=SP // State with 2 digits
billing.postcode=04538905 //postcode with 8 numeric digits, no dashes, spaces or slashes.
billing.country=BR //Country with 2 digits
customer.givenName=Gustavo
customer.surname=Santos
customer.ip=1.1.1.1
customer.email=test@test.com
customer.identificationDocType=TAXSTATEMENT // Type of the identification DOC. Needed as you need to send a CPF.
customer.identificationDocId=70383053102 //CPF number of end customer
//end of shopper details

customParameters[CUSTOM_due_date]=21012018 //Due date of the Boleto. We recommend 3 days of the issuance date
merchantTransactionId=1234
shopperResultUrl=http://google.com  //Although there is no re-direct back from the Boleto to your shop, our API requires this parameter to be present
testMode=EXTERNAL // only required on staging. Please remove on production environment`
```

**The collection of the CPF (Tax Identification number) is mandatory for all payments in Brazil. It is also mandatory to verify the CPF via this Java Script:** [**https://gist.github.com/cauerego/873308**](https://gist.github.com/cauerego/873308)

#### **Successful Response**

**Successful Response**

```
{
"id":"8a82944964ea186c0164ecbf445f7385",
"paymentType":"PA",
"paymentBrand":"BOLETO",
"amount":"10.00",
"currency":`"BRL",
"descriptor":"Test Merchant 2460.0146.3970 Virtual Goods",
"merchantTransactionId":"1234",
"result":{
    "code":"000.100.112",
    "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
},
"resultDetails":{
    "ExtendedDescription":"Payment method ready to be captured",
    "BarCodeNumber":"00094666000000010009999252460014639799999990",
    "connectorId":"beb52023-ea89-4750-9a82-75525d189249",
    "ConnectorTxID2":"1234",
    "DigitableLine":"00099.99921 52460.014633 97999.999903 4 66600000001000",
    "AcquirerResponse":"1",
    "reconciliationId":"1234"
},
"customer":{
   "givenName":"Pagador",
   "surname":"Pagador",
   "email":"test@test.com",
   "identificationDocType":"TAXSTATEMENT",
   "identificationDocId":"11111111111",
   "ip":"1.1.1.1"
},
"billing":{
   "street1":"Av Brigadeiro Faria Lima 3729 ",
   "city":"Sao Paulo",
   "state":"SP",
   "postcode":"04538905",
   "country":"BR"
},
"customParameters":{
   "CUSTOM_due_date":"21012018"
},
"redirect":{
    "url":"[https://transactionsandbox.pagador.com.br/post/pagador/reenvia.asp/beb52023-ea89-4750-9a82-75525d189249"](https://transactionsandbox.pagador.com.br/post/pagador/reenvia.asp/beb52023-ea89-4750-9a82-75525d189249%22),
    "parameters":[
]},
"buildNumber":"ff2430ab706f7ca0b5b903b11604719f5424d21c@2018-07-27 10:29:18 +0000",
"timestamp":"2018-07-30 19:51:58+0000",
"ndc":"8a8294174ae82ada014aedfd75aa1d79_dca6a0b62dc44d0e81195603af6f39a7"
}
```

#### **Re-directing the shopper**

From the success response you will be able to extract the URL to where you re-direct the shopper to in order to display the Boleto itself. Please note that the staging environment of the bank may show an error from time to time instead of the actual Boleto.

#### **Retrieve notifications when the Boleto is paid**

**Please refer to section** [**webhooks**](https://primeiropay.atlassian.net/wiki/spaces/MS/pages/603291718/Webhooks)

**Sample webhook of a paid Boleto**

```
[
    2018-07-30
][
    19:57:13,
    046
]Notification b8d00c6a-276b-4816-a423-a7996e376834 message:{
    "type":"PAYMENT",
    "payload":{
        "id":"8a82944a64ea2a060164ecc41d671606",
        "referencedId":"8a82944a64ea2a060164ecc06db70bce",
        "paymentType":"RC",
        "amount":"10.0",
        "currency":"BRL",
        "presentationAmount":"10.0",
        "presentationCurrency":"BRL",
        "descriptor":"Test Merchant 6086.5776.5026 Virtual Goods",
        "merchantTransactionId":"****",
        "result":{
            "code":"000.100.112",
            "description":"Request successfully processed in 'Merchant in Connector Test Mode'",
            "randomField621972632":"Please allow for new unexpected fields to be added"
        },
        "customer":{
            "givenName":"Pagador",
            "surname":"Pagador",
            "email":"test@test.com",
            "identificationDocType":"TAXSTATEMENT",
            "identificationDocId":"11111111111",
            "ip":"1.1.1.1"
        },
        "billing":{
            "street1":"Av Brigadeiro Faria Lima ****",
            "city":"Sao Paulo",
            "state":"SP",
            "postcode":"04538905",
            "country":"BR"
        },
        "authentication":{
            "entityId":"8a8294174ae82ada014aedfd75aa1d79"
        },
        "customParameters":{
            "INFO_matchingAlgorithm":"MANUAL_MATCH"
        },
        "redirect":{
            "parameters":[
                
            ]
        },
        "risk":{
            "score":""
        },
        "timestamp":"2018-07-30 19:57:12+0000",
        "ndc":"DFCAD1AC1C0E00977B5A9FFE0E85AB3D.sbg-vm-bip01_1234_rand3cd6e14412f83147"
    }
}
```

#### **Field specifications**

| **Name**                          | **Description**                                                                    | **Format**                                             | **Example**                                                         |
| --------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
| Authorization Bearer (Header)     | Authentication token used to identify the merchant.                                | AN a-zA-Z0- 9\_                                        | Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA== |
| amount                            | Amount of the payment request. The dot is used as a decimal separator.             | N13 0- 9{1,10}.0 -9{2}                                 | 1.00                                                                |
| currency                          | Currency Code according to ISO 4217 specifications of the payment request’s amount | A3 a-zA-Z{3}                                           | BRL                                                                 |
| paymentBrand                      | The brand specifies the method for the request                                     | AN32 a-zA-Z0- 9\_ {1,32}                               | BOLETO                                                              |
| paymentType                       | The payment type for the request                                                   | A2                                                     | PA                                                                  |
| entityId                          | The entity for the request. (e.g. channel)                                         | AN32 a-zA-Z0- 9{32}                                    | 8a8294174ae82ada014 aedfd75aa1d79                                   |
| customer.email                    | The (internal) email address of the customer                                       | AN128 \s\S{6,12 8}                                     | <test@test.com>                                                     |
| customer.ip                       | AN255 \s\S{1,25 5}                                                                 | AN255 \s\S{1,25 5}                                     | 1.1.1.1                                                             |
| customer.identificationDocId      | CPF number of customer or CNPJ of the company                                      | N11 or N14                                             | 50439917476 or 50966454000190                                       |
| merchantTransactionID             | Merchant-provided reference number                                                 | AN255 \s\S{1,25 5}                                     | 1234                                                                |
| customParametersCUSTOM\_due\_date | Due Date of the Boleto. Recommended: 3 days in the future.Format: DDMMYYYY         | AN10 {19/20}(0-9{2})-(01-9/10-2)-(01-9/10-9/20-9/30-1) | 21012016                                                            |

{% file src="/files/-MGhgFZpkLZ6i465dKST" %}
Boleto Json Request
{% endfile %}


# Baloto

&#x20;Baloto is one of Columbia’s most popular cash payment methods. It allows customers to pay bills, send and collect money electronically. Baloto’s popularity is due to its convenient voucher system. The customer receives a voucher reference number which can be paid at more than 10,000 stores across Columbia.

**Baloto is a server to server only payment method to increase conversion**

| Transaction Types | Meaning                                                                                                                                                              | Success return codes                 |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| PA                | Successful generation of the Baloto payment slip. The shopper can go and pay for it at any Oxxo store in Mexico.                                                     | 000.000.000 000.100.112 (on staging) |
| RC                | Successful payment of the Baloto payment slip. The payment of the Oxxo slip is asynchronous and hence the confirmation will usually come in within 1-3 business days | 000.000.000                          |

#### **Initial Request**

```
//send POST to https://test.oppwa.com/v1/payments 
//Header -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMj1234E2YTE1YjB8ZjJGRUtacXRCUA==" 
//API credentials 
entityId=8a8294174ae8145684aedfd75aa1d79 //entityId without authentication"
//API credentials end
amount=10.00 
paymentType=PA 
currency=COP 
merchantTransactionId=123456 
paymentBrand=BALOTO 
billing.country=CO 
shopperResultUrl=http://google.com //Although there is no re-direct back from the Boleto to your shop, our API requires this parameter to be present 
testMode=EXTERNAL
```

#### **Successful Response**

```
{ 
    "id": "8ac7a49f6855fc58016858092e4d6e26", 
    "paymentType": "PA", 
    "paymentBrand": "BALOTO", 
    "amount": "10.00", "currency": 
    "COP", "descriptor": "9201.9521.3874 Baloto_Test_Mexico ", 
    "merchantTransactionId": "123456", 
    "result": { 
        "code": "000.100.112", 
        "description": "Request successfully processed in 'Merchant in Connector Test Mode'" 
    }, 
    "resultDetails": { 
        "ExtendedDescription": 
        "Transaction succeeded", "AuthCode": "700000000001431901201900010005", 
        "ConnectorTxID1": "8ac7a49f6855fc58016858092e4d6e26", 
        "AcquirerResponse": "00" 
    }, 
    "billing": { 
        "country": "CO" 
    }, 
    "redirect": { 
        "url": "https://primeiropay.com/BALOTO/beda6dbe14f845e2a2e30658b437b32432", 
        "method": "GET", 
        "parameters": [ 
        ] 
     }, 
     "buildNumber": "7a657990dc4e456c4b1f78eb30c06a0a20b76d67@2019-01-15 12:29:51 +0000", 
     "timestamp": "2019-01-16 19:00:25+0000", 
     "ndc": "8a82941865d7e66c0165e76a6d861c1e_171ecf9107ae48a4a751bb85490c94fe" 
}
```

#### **Re-directing the shopper**

From the success response you will be able to extract the URL to where you re-direct the shopper to in order to display the Baloto slip itself. Please note that the staging environment of the bank may show an error from time to time instead of the actual payment slip.

####

**Retrieve notifications when the Baloto slip is paid**

**Please refer to section** [**webhooks**](http://primeiropay.atlassian.net/wiki/spaces/MS/pages/603291718/Webhooks)

```
{
   "type":"PAYMENT",
   "payload":{
      "id":"8ac7a49f6855fc58016858092e4d6e26",
      "paymentType":"PA",
      "paymentBrand":"BALOTO",
      "amount":"10.0",
      "currency":"COL",
      "presentationAmount":"10.0",
      "presentationCurrency":"COL",
      "descriptor":"9201.9521.3874 Baloto_Test_Mexico ",
      "merchantTransactionId":"123456",
      "result":{
         "code":"000.100.112",
         "description":"Request successfully processed in 'Merchant in Connector Test Mode'",
         "randomField983954327":"Please allow for new unexpected fields to be added"
      },
      "resultDetails":{
         "ExtendedDescription":"Transaction succeeded",
         "AcquirerResponse":"00",
         "AuthCode":"700000000001431901201900010005",
         "ConnectorTxID1":"8ac7a49f6855fc58016858092e4d6e26"
      },
      "billing":{
         "country":"CO"
      },
      "authentication":{
         "entityId":"8a82941865d7e66c0165e76a6d861c1e"
      },
      "redirect":{
         "url":"https://primeiropay.com/BALOTO/beda6dbe14f845e2a2e30658b437b32432",
         "method":"GET",
         "parameters":[
            {
               "name":"barcode",
               "value":"700000000001431901201900010005"
            }
         ]
      },
      "risk":{
         "score":""
      },
      "timestamp":"2019-01-16 19:00:25+0000",
      "ndc":"8a82941865d7e66c0165e76a6d861c1e_171ecf9107ae48a4a751bb85490c94fe",
      "merchantAccountId":"8a82941865d7e66c0165e76c483f1c26"
   }
}
```

#### **Field specifications**

| **Name**              | **Description**                                                                    | **Format**               | **Example**                       |
| --------------------- | ---------------------------------------------------------------------------------- | ------------------------ | --------------------------------- |
| amount                | Amount of the payment request. The dot is used as a decimal separator.             | N13 0- 9{1,10}.0 -9{2}   | 1.00                              |
| currency              | Currency Code according to ISO 4217 specifications of the payment request’s amount | A3 a-zA-Z{3}             | COP                               |
| paymentBrand          | The brand specifies the method for the request                                     | AN32 a-zA-Z0- 9\_ {1,32} | BALOTO                            |
| paymentType           | The payment type for the request                                                   | A2                       | PA                                |
| entityId              | The entity for the request. (e.g. channel)                                         | AN32 a-zA-Z0- 9{32}      | 8a8294174ae82ada014 aedfd75aa1d79 |
| merchantTransactionID | Merchant-provided reference number                                                 | AN255 \s\S{1,25 5}       | 1234                              |
| billing.country       | Billing Country (has to be MX for Baloto to work.)                                 | A2                       | MX                                |

{% file src="/files/-MGhgMN5KtalzB5BfAJk" %}
Baloto Json Request
{% endfile %}


# Oxxo

&#x20;Oxxo is a Mexican voucher-based payment method. Shoppers order items online, select Oxxo at checkout and receive a voucher. Then, they pay in cash for their purchase with that voucher at one of the over 13,000 OXXO stores in the country. Because many people in Mexico don't have a bank account or credit card, this is a popular eCommerce payment method.

**Oxxo is a server to server only payment method to increase conversion**

| Transaction Types | Meaning                                                                                                                                                            | Success return codes                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| PA                | Successful generation of the Oxxo payment slip. The shopper can go and pay for it at any Oxxo store in Mexico.                                                     | 000.000.000 000.100.112 (on staging) |
| RC                | Successful payment of the Oxxo payment slip. The payment of the Oxxo slip is asynchronous and hence the confirmation will usually come in within 1-3 business days | 000.000.000                          |

#### **Initial Request**

**API Endpoint:** [**https://test.oppwa.com/v1/payments**](https://test.oppwa.com/v1/payments)

```
//send POST to  [https://test.oppwa.com/v1/payments](https://test.oppwa.com/v1/payments)
//Header -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMj1234E2YTE1YjB8ZjJGRUtacXRCUA=="
//API credentials
entityId=8a8294174ae8145684aedfd75aa1d79 //entityId without authentication"
//API credentials end
amount=10.00
paymentType=PA
currency=MXN
merchantTransactionId=123456
paymentBrand=OXXO
billing.country=MX
shopperResultUrl=[http://google.com](http://google.com/)  //Although there is no re-direct back from the Boleto to your shop, our API requires this parameter to be present`
testMode=EXTERNAL
```

#### **Successful Response**

**Successful Response**

```
{
    "id":"8ac7a49f6855fc58016858092e4d6e26",
    "paymentType":"PA",
    "paymentBrand":"OXXO",
    "amount":"10.00",
    "currency":"MXN",
    "descriptor":"9201.9521.3874 BoletosTest_Mexico",
    "merchantTransactionId":"123456",
    "result": {
        "code":"000.100.112",
        "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
    },
    "resultDetails": {
        "ExtendedDescription":"Transaction succeeded",
        "AuthCode":"700000000001431901201900010005",
        "ConnectorTxID1":"8ac7a49f6855fc58016858092e4d6e26",
        "AcquirerResponse":"00"
    },
    "billing": {
    "country":"MX"
    },
    "redirect": {
        "url":"[https://serti.io/primeiro/v1/payments/oxxo/beda6dbe14f845e2a2e30658b437b32432"](https://serti.io/primeiro/v1/payments/oxxo/beda6dbe14f845e2a2e30658b437b32432%22),
        "method":"POST",
        "parameters": [
        ]
    },
    "buildNumber":"7a657990dc4e456c4b1f78eb30c06a0a20b76d67@2019-01-15 12:29:51 +0000",
    "timestamp":"2019-01-16 19:00:25+0000",
    "ndc": "8a82941865d7e66c0165e76a6d861c1e_171ecf9107ae48a4a751bb85490c94fe"
}
```

#### **Re-directing the shopper**

From the success response you will be able to extract the URL to where you re-direct the shopper to in order to display the Oxxo slip itself. Please note that the staging environment of the bank may show an error from time to time instead of the actual payment slip.

#### **Retrieve notifications when the Oxxo slip is paid**

**Please refer to section** [**webhooks**](https://primeiropay.atlassian.net/wiki/spaces/MS/pages/603291718/Webhooks)

**Sample webhook of a paid Boleto**

```
{
   "type":"PAYMENT",
   "payload":{
      "id":"8ac7a49f6855fc58016858092e4d6e26",
      "paymentType":"PA",
      "paymentBrand":"OXXO",
      "amount":"10.0",
      "currency":"MXN",
      "presentationAmount":"10.0",
      "presentationCurrency":"MXN",
      "descriptor":"9201.9521.3874 BoletosTest_Mexico ",
      "merchantTransactionId":"123456",
      "result":{
         "code":"000.100.112",
         "description":"Request successfully processed in 'Merchant in Connector Test Mode'",
         "randomField983954327":"Please allow for new unexpected fields to be added"
      },
      "resultDetails":{
         "ExtendedDescription":"Transaction succeeded",
         "AcquirerResponse":"00",
         "AuthCode":"700000000001431901201900010005",
         "ConnectorTxID1":"8ac7a49f6855fc58016858092e4d6e26"
      },
      "billing":{
         "country":"MX"
      },
      "authentication":{
         "entityId":"8a82941865d7e66c0165e76a6d861c1e"
      },
      "redirect":{
         "url":"[https://serti.io/primeiro/v1/payments/oxxo/beda6dbe14f845e2a2e30658b437b323",
         "method":"POST",
         "parameters":[
            {
               "name":"barcode",
               "value":"700000000001431901201900010005"
            }
         ]
      },
      "risk":{
         "score":""
      },
      "timestamp":"2019-01-16](https://serti.io/primeiro/v1/payments/oxxo/beda6dbe14f845e2a2e30658b437b323%22,%22method%22:%22POST%22,%22parameters%22:[%7B%22name%22:%22barcode%22,%22value%22:%22700000000001431901201900010005%22%7D]%7D,%22risk%22:%7B%22score%22:%22%22%7D,%22timestamp%22:%222019-01-16) 19:00:25+0000",
      "ndc":"8a82941865d7e66c0165e76a6d861c1e_171ecf9107ae48a4a751bb85490c94fe",
      "merchantAccountId":"8a82941865d7e66c0165e76c483f1c26"
   }
}
```

| **Description**         | **Format**                                                                         | **Example**              |                                   |
| ----------------------- | ---------------------------------------------------------------------------------- | ------------------------ | --------------------------------- |
| amount                  | Amount of the payment request. The dot is used as a decimal separator.             | N13                      |                                   |
| 0- 9{1,10}.0 -9{2}      | 1.00                                                                               |                          |                                   |
| currency                | Currency Code according to ISO 4217 specifications of the payment request’s amount | A3 a-zA-Z{3}             | MXN                               |
| paymentBrand            | The brand specifies the method for the request                                     | AN32 a-zA-Z0- 9\_ {1,32} | BOLETO                            |
| paymentType             | The payment type for the request                                                   | A2                       | PA                                |
| Authentication.userID   | The userId for the entity. Required for a server-to-server request                 | AN32 a-zA-Z0- 9{32}      | 8a8294174ae82ada014 aedf7fb151d5f |
| Authentication.password | The password for the entity (channel). Required for a server-to-server request     | AN32 a-zA-Z0- 9{8,32}    | AKdx7nmH                          |
| authentication.entityId | The entity for the request. (e.g. channel)                                         | AN32 a-zA-Z0- 9{32}      | 8a8294174ae82ada014 aedfd75aa1d79 |
| merchantTransactionID   | Merchant-provided reference number                                                 | AN255 \s\S{1,25 5}       | 1234                              |
| billing.country         | Billing Country (has to be MX for Oxxo to work.)                                   | A2                       | MX                                |

{% file src="/files/-MGhgcf3Bj-Hi0BBL5pr" %}
Oxxo Json Request
{% endfile %}


# PagoEfectivo

&#x20;To use PagoEfectivo, you have to use follow their brand guide, listed below:

[Brand guide](https://drive.google.com/drive/u/0/folders/1258YHDK-h5wiHV8YWez8Mz1pyeTRwN_C)

[Logos, manuals, fonts](https://drive.google.com/drive/folders/1BY3OB6n1fA4XGQrd2rxGwLFVE8buwN1Y)

| **Country** | **Currency Accepted** |
| ----------- | --------------------- |
| Ecuador     | USD                   |
| Peru        | PEN, USD              |

⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀

| Transactions Types | Meaning                                                                                                                                                                           | Success return codes                 |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| RC                 | Successful generation of the PagoEfectivo payment slip.                                                                                                                           | 000.000.000 000.100.112 (on staging) |
| PA                 | Successful payment of the PagoEfectivo payment slip. The payment of the PagoEfectivo slip is asynchronous and but usully takes up to 5 mintes after the shopper pays to be shown. | 000.000.000                          |

⠀⠀⠀⠀⠀⠀

#### **Initial Request**

```
//send POST to https://test.oppwa.com/v1/payments 
//Header -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMj1234E2YTE1YjB8ZjJGRUtacXRCUA==" 
//API credentials entityId=8a8294174ae8145684aedfd75aa1d79 //entityId without authentication" 
//API credentials end 
amount=10.00 
paymentType=PA 
currency=COL 
merchantTransactionId=123456 
paymentBrand=PAGO_EFECTIVO 
customParameters[CUSTOM_due_date]=23032020 122343 //optional. DDMMAAAA HHMMSS. If not set, default is 3 days. 
customParameters[DOCTYPE]=DNI //optional. Can be one of the following: DNI (Documento nacional de identidad),PAR (Partida),PAS (Pasaporte),LMI (Libreta militar),NAN (another type) 
customParameters[DOCNUMBER]=21321321321354 //14 digits, numeric only. 
customer.phone=32523534532 //optional, phone number with country code. If sent, will be used to send SMS reminders by Pago_Efectivo. 
customer.email=teste@teste.com // optional. 
customer.givenName=Peter //optional 
customer.surname=Prado //optional 
billing.postcode=232424//optional 
billing.country=PE -> Use country code = service render country. EG: PE 
shopperResultUrl=http://google.com //Although there is no re-direct back from PagoEfectivo slip to your shop, our API requires this parameter to be present 
testMode=EXTERNAL // Send this only on test. Delete this entry in live.
```

#### **Successful Response**

```
{ 
     "id":"8ac7a49f6855fc5801685805636585566", 
     "paymentType":"PA", 
     "paymentBrand":"PAGO_EFECTIVO", 
     "amount":"10.0", 
     "currency":"COL", 
     "presentationAmount":"10.0", 
     "presentationCurrency":"COL", 
     "descriptor":"9201.9521.3874", 
     "merchantTransactionId":"123456", 
     "result":{ 
        "code":"000.100.112", 
        "description":"Request successfully processed in 'Merchant in Connector Test Mode'", 
     }, 
     "resultDetails":{ 
        "ExtendedDescription":"Solicitud exitosa", 
        "AcquirerResponse":"100", 
        "ConnectorTxID1":"2315324" 
     }, 
     "billing":{
        "country":"EC" 
     }, 
     "authentication":{
        "entityId":"8a82941865d7e66c0165e76a6d861c1e" 
     }, 
     "redirect":{ 
        "url":"https://pre1a.payment.pagoefectivo.pe/3EA6FED6-0A17-463C-BE9D-763007D0E7AB.html", 
        "method":"GET", 
        "parameters":[] 
     }, 
     ,"timestamp":"2019-01-16 19:00:25+0000", 
     "ndc":"8a82941865d7e66c0165e76a6d861c1e_171ecf9107ae48a4a751bb85490c94fe", 
     "merchantAccountId":"8a82941865d7e66c0165e76c483f1c26" }
```

#### **Re-directing the shopper**

From the success response you will be able to extract the URL (under redirect → URL) to where you re-direct the shopper to in order to display the PagoEfectivo slip itself. Please note that the staging environment of the bank may show an error from time to time instead of the actual payment slip.

⠀⠀⠀⠀⠀⠀⠀⠀

#### **Retrieve notifications when the Pago-Efectivo slip is paid**

PagoEfectivo use [webhooks](http://primeiropay.atlassian.net/wiki/spaces/MS/pages/603291718/Webhooks) to inform paid slips.

Webhooks with paymentType RC and result\_code = '000.000.000' (or 000.100.112 on staging )are PagoEfectivo payment slips paid.

```
{
   "type":"PAYMENT",
   "payload":{
      "id":"8ac7a49f6855fc58016858092e4d6e26",
      "paymentType":"RC",
      "paymentBrand":"PAGO-EFECTIVO",
      "amount":"10.0",
      "currency":"COL",
      "presentationAmount":"10.0",
      "presentationCurrency":"COL",
      "descriptor":"9201.9521.3874",
      "merchantTransactionId":"123456",
      "result":{
         "code":"000.100.112",
         "description":"Request successfully processed in 'Merchant in Connector Test Mode'",
         "randomField983954327":"Please allow for new unexpected fields to be added"
      },
      "resultDetails":{
         "ExtendedDescription":"Transaction succeeded",
         "AcquirerResponse":"00",
         "AuthCode":"700000000001431901201900010005",
         "ConnectorTxID1":"8ac7a49f6855fc58016858092e4d6e26"
      },
      "billing":{
         "country":"EC"
      },
      "authentication":{
         "entityId":"8a82941865d7e66c0165e76a6d861c1e"
      },
      "redirect":{
         "url":"https://pre1a.payment.pagoefectivo.pe/3EA6FED6-0A17-463C-BE9D-763007D0E7AB.html",
         "method":"GET",
         "parameters":[
            {
               "name":"barcode",
               "value":"700000000001431901201900010005"
            }
         ]
      },
      "risk":{
         "score":""
      },
      "timestamp":"2019-01-16 19:00:25+0000",
      "ndc":"8a82941865d7e66c0165e76a6d861c1e_171ecf9107ae48a4a751bb85490c94fe",
      "merchantAccountId":"8a82941865d7e66c0165e76c483f1c26"
   }
}
```

| **Name**                          | **Description**                                                                                                                                                   | **Format**                                                                                                   | **Example**                                                        |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| amount                            | Amount of the payment request. The dot is used as a decimal separator.                                                                                            | N13 0- 9{1,10}.0 -9{2}                                                                                       | 1.00                                                               |
| currency                          | Currency Code according to ISO 4217 specifications of the payment request’s amount                                                                                | A3 a-zA-Z{3}                                                                                                 | COL                                                                |
| paymentBrand                      | The brand specifies the method for the request                                                                                                                    | AN32 a-zA-Z0- 9\_ {1,32}                                                                                     | PAGO\_EFECTIVO                                                     |
| paymentType                       | The payment type for the request                                                                                                                                  | A2                                                                                                           | PA                                                                 |
| entityId                          | The entity for the request. (e.g. channel)                                                                                                                        | AN32 a-zA-Z0- 9{32}                                                                                          | 8a8294174ae82ada014 aedfd75aa1d79                                  |
| merchantTransactionID             | Merchant-provided reference number                                                                                                                                | AN255 \s\S{1,25 5}                                                                                           | 1234                                                               |
| billing.country                   | Billing Country (has to be EC for PagoEfectivo to work.                                                                                                           | A2                                                                                                           | MX                                                                 |
| customParametersCUSTOM\_due\_date | optional. If not set, default is 3 days. Date and time sent is in UTC.                                                                                            | DDMMAAAA HHMMSS                                                                                              | 23032020 122343                                                    |
| customParametersDOCTYPE           | Optional. Doc type used. Can be one of the following.DNI (Documento nacional de identidad) PAR (Partida) PAS (Pasaporte) LMI (Libreta militar) NAN (another type) | DNI (Documento nacional de identidad) PAR (Partida) PAS (Pasaporte) LMI (Libreta militar) NAN (another type) | DNI                                                                |
| customParametersDOCNUMBER         | Optional. Number of the document.                                                                                                                                 | AN14                                                                                                         | D42342342334523                                                    |
| customer.phone                    | Optional, phone number with country code. If sent, will be used to send SMS reminders by PagoEfectivo.                                                            | N15                                                                                                          | 32523534532                                                        |
| customer.email                    | Optional. Customer email.                                                                                                                                         | AN128 \s\S{6,128}                                                                                            | <teste@teste.com>                                                  |
| customer.givenName                | Optional. Customer first name.                                                                                                                                    | AN \s\S                                                                                                      | Peter                                                              |
| customer.surname                  | Optional. Customer surename                                                                                                                                       | AN \s\S                                                                                                      | Prado                                                              |
| billing.postcode                  | Customer postcode                                                                                                                                                 | AN30 A-Za-z0-9{1,30}                                                                                         | 223224                                                             |
| shopperResultUrl                  | URL                                                                                                                                                               | AN2048 \s\S{6,2048}                                                                                          | [http://www.google.com](http://www.google.com/)                    |
| id                                | Response id that is unique for each transaction                                                                                                                   | AN32                                                                                                         | 8ac7a49f6855fc5801685805636585566                                  |
| resultDetails.ConnectorTxID1      | Acquirer Reference. For PagoEfectivo this is the CIP number                                                                                                       | AN255                                                                                                        | 123141                                                             |
| redirect.url                      | url for the payment slip                                                                                                                                          | AN255                                                                                                        | <https://pagoefectivo.pe/234>                                      |
| redirect.method                   | Method you should use to redirect the shopper to the url                                                                                                          | AN255                                                                                                        | GET                                                                |
| redirect.parameters               | parameters you should add to the URL when redirecting the shopper. may be null                                                                                    | AN255                                                                                                        | payment=234                                                        |
| result.code                       | result code of the transaction. See [ResultCodes](https://primeiropay.docs.oppwa.com/reference/resultCodes)                                                       | nnn.nnn.nnn                                                                                                  | 000.000.000                                                        |
| result.description                | description of the result code                                                                                                                                    | AN255                                                                                                        | “Successfull transaction”                                          |
| resultDetails.ExtendedDescription | acquirer description of their code                                                                                                                                | AN244                                                                                                        | “Solicitud exitosa”                                                |
| resultDetails.AcquirerResponse    | acquirer result code                                                                                                                                              | AN255                                                                                                        | 100                                                                |
| presentationAmount                | amount                                                                                                                                                            | N13 0- 9{1,10}.0 -9{2}                                                                                       | 10.00                                                              |
| presentationCurrency              | currency                                                                                                                                                          | A3 a-zA-Z{3}                                                                                                 | COL                                                                |
| descriptor                        | Descriptor of the transaction                                                                                                                                     | AN255                                                                                                        | PagoEfectivo 232.2939.29323                                        |
| timestamp                         | Timestamp                                                                                                                                                         | YYYY-MM-DD HH:MM:SS+/-HHHH                                                                                   | 2019-01-16 19:00:25+0000                                           |
| ndc                               | Internal id for internal uses. Can be asked in case of an error                                                                                                   | AN255                                                                                                        | 8a82941865d7e66c0165e76a6d861c1e\_171ecf9107ae48a4a751bb85490c94fe |
| merchantAccountId                 | id of your merchant account                                                                                                                                       | AN32                                                                                                         | 8a82941865d7e66c0165e76c483f1c26                                   |
| testMode                          | testMode used on test. Should be EXTERNAL for PagoEfectivo                                                                                                        | AN255                                                                                                        | EXTERNAL                                                           |

{% file src="/files/-MGhgkBQOtpN3LH8CRH\_" %}
PagoEfectivo Json Request
{% endfile %}


# PIX

**PIX is a server to server only payment method to increase conversion.**

| Payment Types | Meaning                                                                                                                                         | Success return codes                              |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| PA            | Successful generation of the PIX QR-Code. The shopper can go and pay for it online or at any supported POS                                      | <p>000.000.000</p><p>000.100.112 (on staging)</p> |
| RC            | Successful payment of PIX. The payment of the PIX is asynchronous and the payment confirmation depends on when the PIX was paid by the consumer | 000.000.000                                       |

### **Initial Request** <a href="#initial-request" id="initial-request"></a>

```
//send POST to https://test.oppwa.com/v1/payments 
//Header -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
amount=10.00
currency=BRL
paymentBrand=PIX
paymentType=PA 
//API credentials
entityId=8a8294174ae82ada014aedfd75aa1d79 
//API credentials end
//Shopper details (all mandatory)
customer.givenName=Gustavo
customer.surname=Santos
customer.identificationDocType=TAXSTATEMENT // Type of the identification DOC. Needed as you need to send a CPF/CNPJ
customer.identificationDocId=70383053102 //CPF/CNPJ number of end customer
//end of shopper details
billing.country="BR"
customParameters[CUSTOM_due_time]=7200 //Due time of the PIX in seconds. 7200 seconds = 2hours. You can also use customParameters[CUSTOM_due_date]=DDMMYYYY. If no expiry date is sent, will be set to 3 days by default.
merchantTransactionId=1234
shopperResultUrl=http://www.primeiropay.com //Although there is no re-direct back from PIX to your shop, our API requires this parameter to be present
testMode=EXTERNAL // only required on staging. Please remove on production environment
```

**The collection of the CPF (Tax Identification number) is mandatory for all payments in Brazil. It is also mandatory to verify the CPF via this Java Script:**[ ![](https://github.githubassets.com/favicon.ico)https://gist.github.com/cauerego/873308 - Connect to preview](https://gist.github.com/cauerego/873308)

### **Successful Response** <a href="#successful-response" id="successful-response"></a>

```
{
   "id":"8a82944964ea186c0164ecbf445f7385",
   "paymentType":"PA",
   "paymentBrand":"PIX",
   "amount":"10.00",
   "currency":"BRL",
   "descriptor":"Test Merchant 2460.0146.3970 Virtual Goods",
   "merchantTransactionId":"1234",
   "result":{
      "code":"000.100.112",
      "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
   },
   "resultDetails":{
      "ExtendedDescription":"Payment method ready to be captured",
      "connectorId":"beb52023-ea89-4750-9a82-75525d189249",
      "ConnectorTxID2":"1234",
      "reconciliationId":"1234"
   },
   "customer":{
      "givenName":"Gustavo",
      "surname":"Santos",
      "identificationDocType":"TAXSTATEMENT",
      "identificationDocId":"70383053102"
   },
   "customParameters":{
      "CUSTOM_due_time":"7200"
   },
   "redirect":{
      "url":"https://pix.primeiropay.com/2313413241414",
      "parameters":[
         
      ]
   },
   "buildNumber":"ff2430ab706f7ca0b5b903b11604719f5424d21c@2018-07-27 10:29:18 +0000",
   "timestamp":"2018-07-30 19:51:58+0000",
   "ndc":"8a8294174ae82ada014aedfd75aa1d79_dca6a0b62dc44d0e81195603af6f39a7"
}
```

### **Re-directing the shopper** <a href="#re-directing-the-shopper" id="re-directing-the-shopper"></a>

From the success response you will be able to extract the URL to where you re-direct the shopper to in order to display the PIX QR-code itself. Please note that the staging environment of the bank may show an error from time to time instead of the actual PIX.

### **Retrieve notifications when the PIX is paid** <a href="#retrieve-notifications-when-the-pix-is-paid" id="retrieve-notifications-when-the-pix-is-paid"></a>

**Please refer to section** [**webhooks**](https://developers.primeiropay.com/webhook-1)

```
[
    2018-07-30
][
    19:57:13,
    046
]Notification b8d00c6a-276b-4816-a423-a7996e376834 message:{
    "type":"PAYMENT",
    "payload":{
        "id":"8a82944a64ea2a060164ecc41d671606",
        "referencedId":"8a82944a64ea2a060164ecc06db70bce",
        "paymentType":"RC",
        "amount":"10.0",
        "currency":"BRL",
        "presentationAmount":"10.0",
        "presentationCurrency":"BRL",
        "descriptor":"Test Merchant 6086.5776.5026 Virtual Goods",
        "merchantTransactionId":"****",
        "result":{
            "code":"000.100.112",
            "description":"Request successfully processed in 'Merchant in Connector Test Mode'",
            "randomField621972632":"Please allow for new unexpected fields to be added"
        },
        "customer":{
            "givenName":"Gustavo",
            "surname":"Santos",
            "identificationDocType":"TAXSTATEMENT",
            "identificationDocId":"70383053102"
        },
        "billing":{
            "country":"BR"
        },
        "authentication":{
            "entityId":"8a8294174ae82ada014aedfd75aa1d79"
        },
        "customParameters":{
            "INFO_matchingAlgorithm":"MANUAL_MATCH"
        },
        "redirect":{
            "parameters":[
                
            ]
        },
        "risk":{
            "score":""
        },
        "timestamp":"2018-07-30 19:57:12+0000",
        "ndc":"DFCAD1AC1C0E00977B5A9FFE0E85AB3D.sbg-vm-bip01_1234_rand3cd6e14412f83147"
    }
}
```

|   |
| - |

### **Field specifications** <a href="#field-specifications" id="field-specifications"></a>

| **Name**                             | **Description**                                                                                                              | **Format**                    | **Example**                                                         |                   |         |         |              |          |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------- | ----------------- | ------- | ------- | ------------ | -------- |
| Authorization Bearer (Header)        | Authentication token used to identify the merchant.                                                                          | AN \[a-zA-Z0- 9\_]            | Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA== |                   |         |         |              |          |
| amount                               | Amount of the payment request. The dot is used as a decimal separator.                                                       | N13\[0- 9]{1,10}\\.\[0 -9]{2} | 1.00                                                                |                   |         |         |              |          |
| currency                             | Currency Code according to ISO 4217 specifications of the payment request’s amount                                           | A3 \[a-zA-Z]{3}               | BRL                                                                 |                   |         |         |              |          |
| paymentBrand                         | The brand specifies the method for the request                                                                               | AN32 \[a-zA-Z0- 9\_] {1,32}   | PIX                                                                 |                   |         |         |              |          |
| paymentType                          | The payment type for the request                                                                                             | A2                            | PA                                                                  |                   |         |         |              |          |
| entityId                             | The entity for the request. (e.g. channel)                                                                                   | AN32 \[a-zA-Z0- 9]{32}        | 8a8294174ae82ada014 aedfd75aa1d79                                   |                   |         |         |              |          |
| customer.identificationDocId         | CPF number of customer or CNPJ of the company                                                                                | N11 or N14                    | <p>50439917476</p><p>or 50966454000190</p>                          |                   |         |         |              |          |
| merchantTransactionID                | Merchant-provided reference number                                                                                           | AN255 \[\s\S]{1,25 5}         | 1234                                                                |                   |         |         |              |          |
| customParameters\[CUSTOM\_due\_time] | <p>Optional. Due Time of the Pix in Seconds.</p><p>Will overwrite customParameters\[CUSTOM\_due\_date] if both are sent.</p> | N10                           | 7200                                                                |                   |         |         |              |          |
| customParameters\[CUSTOM\_due\_date] | <p>Optional. Due Date of PIX.</p><p>Will be set to the date you sent at 23:59:59 UTC</p>                                     | <p>DDMMYYYY</p><p>{19         | 20}(\[0-9]{2})-(0\[1-9]                                             | 1\[0-2])-(0\[1-9] | 1\[0-9] | 2\[0-9] | 3\[0-1])</p> | 21012022 |


# About Pix

Q\&A about PIX

* **Is the dashboard different for PIX and Boleto?**

&#x20;For now there is no difference on BIP between the two, just like the checkout page is hybrid, so is the merchant area.

* **If the payment is cancelled by the shopper, what is the correct flow?**

&#x20;There is no cancelling for Boletos or PIX. On the other hand, if shoppers want a reimbursement, the flow is the same as credit cards, via our API. The credit is made to the consumer in just a few moments.

* **How do Boleto reimbursements work for hybrid payments?**

&#x20;Nothing changes. Our support team will require the same purchase information (payment confirmation and shopper bank details) and follow the current flow.

* **How fast is a PIX payment processed?**

Payment confirmation will appear on your webhook in only 10 seconds. Be aware that you need to proactively follow the information in our platform.

* **How long after the payment is done can the merchant deliver their product?**

&#x20;Any product or services may be authorized immediately after payment confirmation (10 seconds as mentioned above).

* **If there is an issue, when should we report to the Customer Experience team?**

&#x20;Passed an hour from the payment. If in that period you received no confirmation in your reports, we kindly ask you to [open a ticket on our platform](https://primeiropay.atlassian.net/servicedesk/customer/portal/3), including the payment statement the transaction’s unique id (when available) so we can be as agile as possible. &#x20;


# Webhook

### **Introduction** <a href="#introduction" id="introduction"></a>

‌

**Webhooks** are HTTP callbacks that notify you of all *events* you subscribed for on an entity.‌

**Events** can be payments, state changes to payments or transactions connected to a payment (e.g. a chargeback).‌

For PCI compliance, SSL connections using untrusted certificates are not allowed. Please ensure you have a valid SSL certificate chain. Self-signed certificates are not valid.‌

**Availability**

| ​Title                           | ​Title                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Delay**                        | Near real-time. [*What does near real-time mean?*](https://en.wikipedia.org/wiki/Real-time_computing#Near_real-time)​                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Request timeout**              | If we don't receive a response within 30 seconds, the message is considered timed out. It will then be scheduled for *retry*.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **Retries**                      | <p> In case of a failed delivery we store a failed notification for a limited period of time and try sending it again later. Retries are sent at increasing time intervals until either the message is accepted or the maximum retry period of 30 days has been exceeded. After this time the transaction still can be looked up via the reporting endpoints or the BIP. Retry-intervals:</p><ul><li>1 minute</li><li>2 minutes</li><li>4 minutes</li><li>8 minutes</li><li>15 minutes</li><li>30 minutes</li><li>1 hour</li><li>every hour until 30 days have passed since the first attempt.</li></ul> |
| **Beyond the retry period**      | Every day you would receive an summarized email with the newest 100 failed notifications sent to the list of emails configured for this listener. The notifications that were queuing up for the last thirty days will be deleted. You still can get these contents by using the other reporting tools of the platform.                                                                                                                                                                                                                                                                                  |
| **Guarantee on message order**   | <p>​</p><p> There is no guarantee on the order of messages. If you first send request A and then request B, you might retrieve a notification first on B then on A, especially if...</p><ul><li>The time difference between the messages is smaller than the time it takes us to process them</li><li>The receiving server was unavailable for a time. Once the server is up again new notifications will arrive in real time, old notifications however would only be resent once they are retried in the rhythm as specified above.</li></ul>                                                          |
| **Required Client server power** | Please make sure that your server for receiving notifications is able to properly receive the peak-loads that can be caused by the transaction processing on entities you're listening to. Example: If there is a transaction processing peak of 30 transactions/second then you would receive around 30 notifications/second on your webhook URL as well. We recommend asynchronous processing and a receiver cache for scenarios like this.                                                                                                                                                            |

​‌

### **Setup** <a href="#setup" id="setup"></a>

‌

**To setup the webhook for you, please provide your Account Manager or Sales Representative with the following information:**

| URL                | The URL that receives the notifications. It has to be https                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Notification types | The notification types you want to subscribe to. E.g. by selecting PAYMENT the registered URL will receive all payment events happening on this entity and its descendants. You can choose any subset of the available options.                                                                                                                                                                                                                      |
| Fields to include  | <p>The fields you want to receive in payload. E.g. by selecting ALL, payload will include every fields the transaction generates.</p><ul><li><strong>ALL</strong> Payload includes all fields the transaction generates</li><li><strong>NON\_CUSTOMER\_DATA</strong> Payload includes only fields which are not customer data</li></ul>                                                                                                              |
| Wrapper            | <p>If you need to get specific content type for webhooks, you can choose wrapper for it.</p><ul><li><strong>None</strong> No wrapper for webhook body. Content-Type will be text/plain and body will be (encrypted) hexadecimal string.</li><li><strong>JSON</strong> Json wrapper for webhook body. Content-Type will be application/json and body will be wrapped by json example: {"encryptedBody":"\[(encrypted) hexadecimal string]"}</li></ul> |


# Webhook Integration Guide

### Notification content and structure

The notification body contains the type of notification and its payload.

```
{
  "type": [notification_type],
  "action": [status],
  "payload": [content]
}
```

| Parameter | Description                                                                                                                                                                                                                                                                                                                                                                                       | Format                        | Required    |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ----------- |
| type      | <p>Type of the notification</p><ul><li><strong>PAYMENT</strong> This type of notification is sent when a payment is created or updated in the system.</li><li><strong>REGISTRATION</strong> This type of notification is sent when a registration is created or deleted.</li><li><strong>RISK</strong> This type of notification is sent when a risk transaction is created or deleted.</li></ul> | (PAYMENT\|REGISTRATION\|RISK) | required    |
| action    | <p>Indicator of status change. This field is available only if the type is REGISTRATION.</p><ul><li><strong>CREATED</strong> when registration has been created.</li><li><strong>UPDATED</strong> when registration has been updated.</li><li><strong>DELETED</strong> when registration has been deleted.</li></ul>                                                                              | (CREATED\|UPDATED\|DELETED)   | conditional |
| payload   | Content of the notification. If the notification type is payment or registration, the payload's content will be identical to the response you received on the payment or registration.                                                                                                                                                                                                            | JSON                          | required    |

#### Example - payment

```
{
   "type":"PAYMENT",
   "payload":{
      "id":"8a829449515d198b01517d5601df5584",
      "paymentType":"PA",
      "paymentBrand":"VISA",
      "amount":"92.00",
      "currency":"EUR",
      "presentationAmount":"92.00",
      "presentationCurrency":"EUR",
      "descriptor":"3017.7139.1650 OPP_Channel ",
      "result":{
         "code":"000.100.110",
         "description":"Request successfully processed in 'Merchant in Integrator Test Mode'"
      },
      "authentication":{
         "entityId":"8a8294185282b95b01528382b4940245"
      },
      "card":{
         "bin":"420000",
         "last4Digits":"0000",
         "holder":"Jane Jones",
         "expiryMonth":"05",
         "expiryYear":"2018"
      },
      "customer":{
         "givenName":"Jones",
         "surname":"Jane",
         "merchantCustomerId":"jjones",
         "sex":"F",
         "email":"jane@jones.com"
      },
      "customParameters":{
         "SHOPPER_promoCode":"AT052"
      },
      "risk":{
         "score":"0"
      },
      "buildNumber":"ec3c704170e54f6d7cf86c6f1969b20f6d855ce5@2015-12-01 12:20:39 +0000",
      "timestamp":"2015-12-07 16:46:07+0000",
      "ndc":"8a8294174b7ecb28014b9699220015ca_66b12f658442479c8ca66166c4999e78"
   }
}
```

#### Example - registration

```
{
   "type":"REGISTRATION",
   "action": "CREATED",
   "payload":{
      "id":"8a82944a53e6a0150153eaf693584262",
      "paymentBrand":"VISA",
      "result":{
         "code":"000.100.110",
         "description":"Request successfully processed in 'Merchant in Integrator Test Mode'",
         "randomField1315125026":"Please allow for new unexpected fields to be added"
      },
      "card":{
         "bin":"420000",
         "last4Digits":"0000",
         "holder":"Jane Jones"
      },
      "authentication":{
         "entityId":"8a8294174b7ecb28014b9699220015ca"
      },
      "redirect":{
         "parameters":[

         ]
      },
      "risk":{
         "score":""
      },
      "timestamp":"2016-04-06 09:45:41+0000",
      "ndc":"8a8294174b7ecb28014b9699220015ca_b1539494024c411684b544574716e608"
   }
}
```

#### Example - risk

```
{
 "type": "RISK",
  "payload": {
    "id": "8ac9a4a86461239601646522acb26523",
    "referencedId": "8ac9a4a86461239601646522aaf96510",
    "paymentType": "RI",
    "paymentBrand": "VISA",
    "presentationAmount": "0.0",
    "result": {
      "code": "000.000.000",
      "description": "Transaction succeeded"
    },
    "card": {
      "bin": "420000",
      "last4Digits": "0000",
      "holder": "Jane Jones",
      "expiryMonth": "03",
      "expiryYear": "2025"
    },
    "authentication": {
      "entityId": "8a8294174b7ecb28014b9699220015ca"
    },
    "redirect": {
      "parameters": []
    },
    "risk": {
      "score": ""
    },
    "timestamp": "2018-07-04 11:52:08+0000",
    "ndc": "8a8294174b7ecb28014b9699220015ca_b1539494024c411684b544574716e608"
  }
}
```

#### [Encryption](https://primeiropay.docs.oppwa.com/tutorials/webhooks/integration-guide#encryption)

The content of notification is encrypted to protect data from fraud attempts. When converting human-readable string to hexadecimal format, we use UTF-8.

| Parameter             | Description                                                                   |
| --------------------- | ----------------------------------------------------------------------------- |
| Encryption algorithm  | AES                                                                           |
| Key                   | \[secret of listener] (64-character-long hexadecimal string in configuration) |
| Key length            | 256 bits (32 bytes)                                                           |
| Block mode            | GCM                                                                           |
| Padding               | None                                                                          |
| Initialization vector | In HTTP header (X-Initialization-Vector)                                      |
| Authentication tag    | In HTTP header (X-Authentication-Tag)                                         |

Format of body: Hexadecimal\
Format of Initialization Vector: Hexadecimal

**Example**

```
Payload
{"type": "PAYMENT"}

Payload in Hexadecimal (after getting bytes in UTF-8)
7B2274797065223A20225041594D454E54227D

Key in Hexadecimal
000102030405060708090A0B0C0D0E0F000102030405060708090A0B0C0D0E0F

Initialization-Vector (Hexadecimal)
3D575574536D450F71AC76D8

Authentication-Tag (Hexadecimal)
19FDD068C6F383C173D3A906F7BD1D83

Encrypted value in Hexadecimal
F8E2F759E528CB69375E51DB2AF9B53734E393
```

### Responding to Notifications

When your service receives a webhook notification, it must return a **2xx** HTTP status code. Otherwise, the webhook service considers the notification delivery as failed, and will retry to send the notification later.

### Protocol Details

| Protocol     | HTTPS (HTTP is allowed on test systems only) |
| ------------ | -------------------------------------------- |
| HTTP method  | POST                                         |
| Content type | text(text/plain)                             |


# Examples for decrypting message

{% tabs %}
{% tab title="C#" %}

```
using System;
using System.Linq;
using System.Text;
using Org.BouncyCastle.Crypto.Engines;
using Org.BouncyCastle.Crypto.Modes;
using Org.BouncyCastle.Crypto.Parameters;
 
namespace DecryptionExample
{
    // You need to install bccrypto-csharp from BouncyCastle. Please see BouncyCastle page.
    class Program
    {
        static void Main(string[] args)
        {
            string keyFromConfiguration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f";
 
            // Data from server
            string ivFromHttpHeader = "000000000000000000000000";
            string authTagFromHttpHeader = "CE573FB7A41AB78E743180DC83FF09BD";
            string httpBody = "0A3471C72D9BE49A8520F79C66BBD9A12FF9";
 
            // Convert data to process
            byte[] key = ToByteArray(keyFromConfiguration);
            byte[] iv = ToByteArray(ivFromHttpHeader);
            byte[] authTag = ToByteArray(authTagFromHttpHeader);
            byte[] encryptedText = ToByteArray(httpBody);
            byte[] cipherText = encryptedText.Concat(authTag).ToArray();
 
            // Prepare decryption
            GcmBlockCipher cipher = new GcmBlockCipher(new AesFastEngine());
            AeadParameters parameters = new AeadParameters(new KeyParameter(key), 128, iv);
            cipher.Init(false, parameters);
 
            // Decrypt
            var plainText = new byte[cipher.GetOutputSize(cipherText.Length)];
            var len = cipher.ProcessBytes(cipherText, 0, cipherText.Length, plainText, 0);
            cipher.DoFinal(plainText, len);
            Console.WriteLine(Encoding.ASCII.GetString(plainText));
        }
 
        static byte[] ToByteArray(string HexString)
        {
            int NumberChars = HexString.Length;
            byte[] bytes = new byte[NumberChars / 2];
            for (int i = 0; i < NumberChars; i += 2)
            {
                bytes[i / 2] = Convert.ToByte(HexString.Substring(i, 2), 16);
            }
            return bytes;
        }
    }
}
```

{% endtab %}

{% tab title="Groovy" %}

```
import org.bouncycastle.jce.provider.BouncyCastleProvider
 
import javax.crypto.spec.IvParameterSpec
import javax.crypto.spec.SecretKeySpec
import java.security.Security
 
// For Java and JVM-based languages, you might need to install unrestricted policy file for JVM, 
// which is provided by Sun. Please refer BouncyCastle FAQ if you get 
// java.lang.SecurityException: Unsupported keysize or algorithm parameters or
// java.security.InvalidKeyException: Illegal key size.

// If you cannot install unrestricted policy file for JVM because of some reason, you can try with reflection: See here.
 
class Cipher {
    static void main(String[] args) {
        Security.addProvider(new BouncyCastleProvider())
 
        // Data from configuration
        def keyFromConfiguration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f"
 
        // Data from server
        def ivFromHttpHeader = "000000000000000000000000"
        def authTagFromHttpHeader = "CE573FB7A41AB78E743180DC83FF09BD"
        def httpBody = "0A3471C72D9BE49A8520F79C66BBD9A12FF9"
 
        // Convert data to process
        def key = keyFromConfiguration.decodeHex()
        def iv = ivFromHttpHeader.decodeHex()
        def authTag = authTagFromHttpHeader.decodeHex() as Byte[]
        def encryptedText = httpBody.decodeHex() as Byte[]
 
        // Unlike other programming language, We have to append auth tag at the end of encrypted text
        def cipherText = encryptedText + authTag as Byte[]
 
        // Prepare decryption
        def keySpec = new SecretKeySpec(key, 0, 32, "AES")
        def cipher = javax.crypto.Cipher.getInstance("AES/GCM/NoPadding")
        cipher.init(javax.crypto.Cipher.DECRYPT_MODE, keySpec, new IvParameterSpec(iv))
 
        // Decrypt
        def result = cipher.doFinal(cipherText)
        println(new String(result, "UTF-8"))
    }
}
```

{% endtab %}

{% tab title="Java" %}

```
import com.google.common.base.Charsets;
import org.apache.commons.lang3.ArrayUtils;
import org.bouncycastle.jce.provider.BouncyCastleProvider;
import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
import java.security.Security;
 
// For Java and JVM-based languages, you might need to install unrestricted policy file for JVM, 
// which is provided by Sun. Please refer BouncyCastle FAQ if you get 
// java.lang.SecurityException: Unsupported keysize or algorithm parameters or
// java.security.InvalidKeyException: Illegal key size.

// If you cannot install unrestricted policy file for JVM because of some reason, you can try with reflection: See here.
 
public class Decryption
{
    public static void main(String[] args) throws Exception
    {
        Security.addProvider(new BouncyCastleProvider());
 
        // Data from configuration
        String keyFromConfiguration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f";
 
        // Data from server
        String ivFromHttpHeader = "000000000000000000000000";
        String authTagFromHttpHeader = "CE573FB7A41AB78E743180DC83FF09BD";
        String httpBody = "0A3471C72D9BE49A8520F79C66BBD9A12FF9";
 
        // Convert data to process
        byte[] key = DatatypeConverter.parseHexBinary(keyFromConfiguration);
        byte[] iv = DatatypeConverter.parseHexBinary(ivFromHttpHeader);
        byte[] authTag = DatatypeConverter.parseHexBinary(authTagFromHttpHeader);
        byte[] encryptedText = DatatypeConverter.parseHexBinary(httpBody);
 
        // Unlike other programming language, We have to append auth tag at the end of encrypted text in Java
        byte[] cipherText = ArrayUtils.addAll(encryptedText, authTag);
 
        // Prepare decryption
        SecretKeySpec keySpec = new SecretKeySpec(key, 0, 32, "AES");
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        cipher.init(Cipher.DECRYPT_MODE, keySpec, new IvParameterSpec(iv));
 
        // Decrypt
        byte[] bytes = cipher.doFinal(cipherText);
        System.out.println(new String(bytes, Charsets.UTF_8));
    }
}
```

{% endtab %}

{% tab title="Node.js" %}

```
var crypto = require("crypto");
 
// Data from configuration
var secretFromConfiguration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f";
 
// Data from server
var ivfromHttpHeader = "000000000000000000000000";
var authTagFromHttpHeader = "CE573FB7A41AB78E743180DC83FF09BD";
var httpBody = "0A3471C72D9BE49A8520F79C66BBD9A12FF9";
 
// Convert data to process
var key = new Buffer(secretFromConfiguration, "hex");
var iv = new Buffer(ivfromHttpHeader, "hex");
var authTag = new Buffer(authTagFromHttpHeader, "hex");
var cipherText = new Buffer(httpBody, "hex");
 
// Prepare descryption
var decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
decipher.setAuthTag(authTag);
 
// Decrypt
var result = decipher.update(cipherText) + decipher.final();
console.log(result);
```

{% endtab %}

{% tab title="Php" %}

```
<?php
/* Php 7.1 or later */
    $key_from_configuration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f";
    $iv_from_http_header = "000000000000000000000000";
    $auth_tag_from_http_header = "CE573FB7A41AB78E743180DC83FF09BD";
    $http_body = "0A3471C72D9BE49A8520F79C66BBD9A12FF9";
    
    $key = hex2bin($key_from_configuration);
    $iv = hex2bin($iv_from_http_header);
    $auth_tag = hex2bin($auth_tag_from_http_header);
    $cipher_text = hex2bin($http_body);
    
    $result = openssl_decrypt($cipher_text, "aes-256-gcm", $key, OPENSSL_RAW_DATA, $iv, $auth_tag);
    print($result);
    
/* Php prior to 7.1 */
    /* Please refer Using Libsodium in PHP Projects */
    $key_from_configuration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f";
    $iv_from_http_header = "000000000000000000000000";
    $auth_tag_from_http_header = "CE573FB7A41AB78E743180DC83FF09BD";
    $http_body = "0A3471C72D9BE49A8520F79C66BBD9A12FF9";
    
    $key = hex2bin($key_from_configuration);
    $iv = hex2bin($iv_from_http_header);
    $cipher_text = hex2bin($http_body . $auth_tag_from_http_header);
    
    $result = \Sodium\crypto_aead_aes256gcm_decrypt($cipher_text, NULL, $iv, $key);
    print($result);
?>
```

{% endtab %}

{% tab title="Phyton" %}

```
import os
import binascii
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
from cryptography.hazmat.backends import default_backend
 
# Data from configuration
key_from_configuration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f"
 
# Data from server
iv_from_http_header = "000000000000000000000000"
auth_tag_from_http_header = "CE573FB7A41AB78E743180DC83FF09BD"
http_body = "0A3471C72D9BE49A8520F79C66BBD9A12FF9"
 
# Convert data to process
key = binascii.unhexlify(key_from_configuration)
iv = binascii.unhexlify(iv_from_http_header)
auth_tag = binascii.unhexlify(auth_tag_from_http_header)
cipher_text = binascii.unhexlify(http_body)
 
# Prepare decryption
decryptor = Cipher(algorithms.AES(key), modes.GCM(iv, auth_tag), backend = default_backend()).decryptor()
 
# Decrypt
result = decryptor.update(cipher_text) + decryptor.finalize()
print(result)
```

{% endtab %}

{% tab title="Ruby" %}

```
require("openssl")
 
# Convert hexadecimal string
def convert(hex)
    return [hex].pack("H*")
end
 
# Create new decipher
def new_decipher(key, iv)
    cipher = OpenSSL::Cipher.new("aes-256-gcm")
    cipher.decrypt
    cipher.key = key
    cipher.iv = iv
     
    return cipher
end
 
# Data from configuration
key_from_configuration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f"
 
# Data from server
iv_from_http_header = "000000000000000000000000"
auth_tag_from_http_header = "CE573FB7A41AB78E743180DC83FF09BD"
http_body = "0A3471C72D9BE49A8520F79C66BBD9A12FF9"
 
# Convert data to process
key = convert(key_from_configuration)
iv = convert(iv_from_http_header)
auth_tag = convert(auth_tag_from_http_header)
cipher_text = convert(http_body)
 
# Prepare decryption
decipher = new_decipher(key, iv)
decipher.auth_tag = auth_tag
 
# Decrypt
result = decipher.update(cipher_text) + decipher.final
puts result
```

{% endtab %}

{% tab title="Scala" %}

```
import java.nio.charset.Charset;
import java.security.Security
import java.security.SecureRandom;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
import org.bouncycastle.jce.provider.BouncyCastleProvider
 
// For Java and JVM-based languages, you might need to install unrestricted policy file for JVM, 
// which is provided by Sun. Please refer BouncyCastle FAQ if you get 
// java.lang.SecurityException: Unsupported keysize or algorithm parameters or
// java.security.InvalidKeyException: Illegal key size.

// If you cannot install unrestricted policy file for JVM because of some reason, you can try with reflection: See here.
 
object Cipher {
  def main(args: Array[String]) = {
    Security.addProvider(new BouncyCastleProvider())
 
    // Data from configuration
    val keyFromConfiguration = "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f"
     
    // Data from server
    val ivFromHttpHeader = "000000000000000000000000"
    val authTagFromHttpHeader = "CE573FB7A41AB78E743180DC83FF09BD"
    val httpBody = "0A3471C72D9BE49A8520F79C66BBD9A12FF9"
     
    // Convert data to process
    val key = hexToBin(keyFromConfiguration)
    val iv = hexToBin(ivFromHttpHeader)
    val authTag = hexToBin(authTagFromHttpHeader)
    val encryptedText = hexToBin(httpBody)
     
    // Unlike other programming language, We have to append auth tag at the end of encrypted text
    val cipherText = encryptedText ++ authTag
     
    // Prepare decryption
    val keySpec = new SecretKeySpec(key, 0, 32, "AES")
    val cipher = javax.crypto.Cipher.getInstance("AES/GCM/NoPadding")
    cipher.init(javax.crypto.Cipher.DECRYPT_MODE, keySpec, new IvParameterSpec(iv))
 
    // Decrypt
    val result = cipher.doFinal(cipherText)
    println(new String(result, "UTF-8"))
  }
 
  def hexToBin(hex: String) : Array[Byte] = {
    return DatatypeConverter.parseHexBinary(hex)
  }
}
```

{% endtab %}
{% endtabs %}


# Paysafecard

### **Supported Brands**

| Brand Name  |
| ----------- |
| PAYSAFECARD |

| Transaction Types | Meaning                                               | Success return codes |
| ----------------- | ----------------------------------------------------- | -------------------- |
| DB                | Debit of the card without prior authorization request | 000.000.000          |

### **Create the checkout** <a href="#paysafecard-createthecheckout" id="paysafecard-createthecheckout"></a>

\
**Create the checkout:** [**https://test.oppwa.com/v1/checkouts/**](https://test.oppwa.com/v1/checkouts/)

| <p><code>// GET Request to the following endpoint:</code></p><p><code>//</code><a href="https://test.oppwa.com/v1/checkouts/"><code><https://test.oppwa.com/v1/checkouts/></code></a> </p><p></p><p><code>amount=1.00       //currency has to be EUR on Test environment and BRL on Production</code></p><p><code>currency=EUR</code></p><p><code>paymentType=PA//your API Credentials</code></p><p><code>authentication.userId=8a8294174ae82ada014aedf7fb151d5f</code></p><p><code>authentication.password=AKdx7nmH</code></p><p><code>authentication.entityId=8a8294174ae82ada014aedfd75aa1d79//end of API Credentialscustomer.ip=1.1.1.1</code></p><p><code>customer.email=<test@test.com></code></p><p><code>merchantTransactionID=1234 //this value will show up on settlement reports and serves as your reference for this transaction</code></p> |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### **Successful Response** <a href="#paysafecard-successfulresponse" id="paysafecard-successfulresponse"></a>

\
**Response Checkout**

| <p><code>{</code>  </p><p>   <code>"result":{</code></p><p>ㅤㅤㅤ<code>"code":"000.200.100",</code></p><p>ㅤㅤㅤ<code>"description":"successfully created checkout"</code></p><p>  <code>},</code>  </p><p>ㅤ<code>"buildNumber":"beb408d1f2c902bfb8665e2b4e268f1039848d03\@2016-02-16 12:49:58 +0000",</code>  </p><p>ㅤ<code>"timestamp":"2016-02-16 13:25:09+0000",</code>  </p><p>ㅤ<code>"ndc":"DA84DCEB01BD28810E992D9EC8085985.sbg-vm-tx01",</code>                      ㅤㅤㅤㅤㅤㅤ<code>"id":"DA84DCEB01BD28810E992D9EC8085985.sbg-vm-tx01"</code></p><p><code>}</code></p> |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

### **Create the Hosted Payment Page / Payment Form** <a href="#paysafecard-createthehostedpaymentpage-paymentform" id="paysafecard-createthehostedpaymentpage-paymentform"></a>

\
**Payment Form**

| <p><code>\<script> // Display the CPF number and set language to Portuguese</code></p><p>   <code>var</code> <code>wpwlOptions ={ showTaxNumberField:true, locale:"pt"}</code></p><p><code>\</script></code></p><p><code>\<scriptsrc=</code> "<a href="https://test.oppwa.com/v1/paymentWidgets.js?checkoutId=75E53EDE2467B24C179501962555376C.sbg-vm-tx02%22"><https://test.oppwa.com/v1/paymentWidgets.js?checkoutId=75E53EDE2467B24C179501962555376C.sbg-vm-tx02>"</a><code>></code></p><p><code>\</script></code></p><p><code>\<form action=" {shopperResultUrl}"</code> <code>class="paymentWidgets">PAYSAFECARD\</form>    // Define the brand PAYSAFECARD and also set the shopper result URL in which the shopper is being redirected to once the payment is conclueded</code></p> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

**You will be re-directed to paysafecard. Please use this code to complete the payment: 1000009011101219**

### **Get the payment status** <a href="#paysafecard-getthepaymentstatus" id="paysafecard-getthepaymentstatus"></a>

Once the payment has been processed, the customer is redirected to your shopperResultUrl along with a GET parameter resourcePath.

**Important**: The baseUrl must end in a "/", e.g. "<https://test.oppwa.com/>".

Then, to get the status of the payment, you should make a GET request to the baseUrl + resourcePath, including your authentication parameters.**Payment status**

| <p><code>//GET Request to the following URL:</code></p><p><code>//</code><a href="https://test.oppwa.com/v1/checkouts/%7BcheckoutId%7D/payment"><code><https://test.oppwa.com/v1/checkouts/{checkoutId}/payment></code></a><code>//The id is what you receive in the previous response once a payment was initiated.</code> <code>authentication.userId=8a8294184e736012014e78a17a6a15b0</code></p><p><code>authentication.entityId=8a8294184e736012014e78a17a5615ac</code></p><p><code>authentication.password=f2FEKZqtBz</code></p> |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

We recommend that you verify the following fields from the Payment Status response, by comparing the returned values with expected:

* ID(s)
* Amount
* Currency
* Brand
* Type

### **Field specifications** <a href="#paysafecard-fieldspecifications" id="paysafecard-fieldspecifications"></a>

| **Name**              | **Description**                                                                    | **Format**                          | **Example**                       |
| --------------------- | ---------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------- |
| amount                | Amount of the payment request. The dot is used as a decimal separator.             | N13\[0- 9]{1,10}\\.\[0 -9]{2}       | 1.00                              |
| currency              | Currency Code according to ISO 4217 specifications of the payment request’s amount | A3 \[a-zA-Z]{3}                     | BRL                               |
| customer.email        | The (internal) email address of the customer                                       | AN128 \[\s\S]{6,12 8}               | <test@test.com>                   |
| customer.ip           | AN255 \[\s\S]{1,25 5}                                                              | AN255 \[\s\S]{1,25 5}               | 1.1.1.1                           |
| merchantTransactionID | Merchant-provided reference number                                                 | AN255 \[\s\S]{1,25 5}               | 1234                              |
| shopperResultUrl      | Result URL after payment is completet                                              | <p>AN2048</p><p>\[\s\S]{6,2048}</p> | <http://merchant.com/success.php> |


# One-Click Checkout

&#x20;This guide allows you to achieve a significant speedup of the checkout process by re-using the data a customer entered for a previous transaction/registration. It's based on one of these two guides:

* The [PrimeiroPay Tokenization Tutorial](https://primeiropay.docs.oppwa.com/widget-tokenisation)
* The [Server-to-Server Tokenization Tutorial](https://primeiropay.docs.oppwa.com/tokenisation)

After the customer account details are stored, as part of the initial transaction/registration, you will need to keep a record of the associated registration IDs (token) that you can then use in step 1 below.

### How it works

### 1. Prepare the checkout

NOTE: For demonstration purposes we have created a registration, which will be used in your one-click checkout, with id(s): 8ac7a4a0739e4f720173a048387d7a7c,8ac7a49f739e470f0173a048391e1c24. Following the guides above, you may add additional registrations options to the checkout.

First perform a server-to-server POST request to prepare the checkout, this should include the registration IDs of the customer as shown below.

The registration IDs should be sent in the `registrations[n].id` parameter, where n is a sequence number from zero, incrementing for each of the customer's registration IDs. For example, if the customer has two accounts on file, you would send `registrations[0].id = {first registration.id}` and `registrations[1].id = {second registration.id}`.

```
curl https://test.oppwa.com/v1/checkouts \
 -d "entityId=8a8294184e736012014e78a17a5615ac" \
 -d "amount=92.00" \
 -d "currency=EUR" \
 -d "paymentType=DB" \
 -d "registrations[0].id=8ac7a4a0739e4f720173a048387d7a7c" \
 -d "registrations[1].id=8ac7a49f739e470f0173a048391e1c24" \
 -d "createRegistration=true" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

Response:

```
{
  "result":{
    "code":"000.200.100",
    "description":"successfully created checkout"
  },
  "buildNumber":"982467e36fd8bc9e74f536ba375c5d0be4fe48eb@2020-07-30 03:42:32 +0000",
  "timestamp":"2020-07-30 15:23:37+0000",
  "ndc":"B20EFF3A508805D585492DDFFE381BCC.uat01-vm-tx03",
  "id":"B20EFF3A508805D585492DDFFE381BCC.uat01-vm-tx03"
}
```

### 2. Create the payment form

Then, to show the payment form you just need to add the following lines of HTML/Javascript to your page and populating the following variables

* The checkout's `id` that you got in the response from step 1

  ```
  <script src="https://test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>
  ```
* The `shopperResultUrl`, which is the page on your site where the customer should be redirected to after the payment is processed and the brands that will be available.

  ```
  <form action="{shopperResultUrl}" class="paymentWidgets">VISA MASTER AMEX</form>
  ```

When Primeiro Pay builds up the payment form it automatically fetches the registrations data from the server and displays the pre-filled widgets to the shopper.

Require CVVShow initial payment from

* html

```
<form action="https://primeiropay.docs.oppwa.com/tutorials/integration-guide/one-click#" class="paymentWidgets">VISA MASTER AMEX</form>
```

* css

```
body {background-color:#f6f6f5;}
```

* js

```
var wpwlOptions = { registrations: { requireCvv: false, hideInitialPaymentForms: true } }
```

* result

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MGjmO_bSsf-ecWdA1dv%2F-MGjnuePcsxwd0F6MRC3%2Fimage.png?alt=media\&token=9cd24bda-f376-4eaf-99bb-903d7ebcabea)

### 3. Get the payment status <a href="#getstatus" id="getstatus"></a>

As usual, once the payment has been processed, the customer is redirected to your `shopperResultUrl` along with a GET parameter `resourcePath`.

IMPORTANT: The baseUrl must end in a "/", e.g. "<https://test.oppwa.com/>".

Then, to get the status of the payment, you should make a GET request to the `baseUrl + resourcePath`, including your authentication parameters.

Example for a resourcePath:

```
resourcePath=/v1/checkouts/{checkoutId}/payment
```

<https://test.oppwa.com/v1/checkouts//payment>

```
curl -G https://test.oppwa.com/v1/checkouts/{id}/payment \
 -d "entityId=8a8294184e736012014e78a17a5615ac" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

We recommend that you verify the following fields from the Payment Status response, by comparing the returned values with expected:

* ID(s)
* Amount
* Currency
* Brand
* Type


# Ckeckout PayPal

**Integration Workflow**

**Sync/Async Processing**

The payment processing works in asynchronous mode. In an asynchronous workflow, a redirection takes place to allow the account holder to complete/verify the payment. After this, the account holder is redirected back to the app and the status of the payment can be queried.

**Workflow**

**Step 1:** Shopper selects PayPal payment method at checkout.&#x20;

**Step 2:** Merchant sends the initial request and redirects the shopper to the returned PayPal redirect url.&#x20;

**Step 3:** Shopper logs into his PayPal account or registers himself.&#x20;

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MGhhO_TGqv2dyIVCgGT%2F-MGhjvpfJkvIc9EVuFbD%2Fimage2017-8-25%2015_16_15.png?alt=media\&token=fe065989-ef63-4fc5-aad9-b427f62beca5)

**Step 4:** The shopper confirms the payment.&#x20;

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MGhhO_TGqv2dyIVCgGT%2F-MGhjzx4nAZrdxKMGhVy%2Fimage2017-8-25%2015_17_29.png?alt=media\&token=7d00a9e2-8cac-4b19-9fb5-571d8077ec0f)

**Step 5:** PayPal approves or declines the transaction.&#x20;

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MGhhO_TGqv2dyIVCgGT%2F-MGhkCcYc2q-rm1lln2g%2Fimage2017-8-25%2015_18_18.png?alt=media\&token=05115bf9-a963-47bd-8dd6-b366b79f1d0f)

**Step 6:** The shopper is redirected back to the shopperResultUrl&#x20;

**Step 7:** The merchant requests the final status of the payment

**Step 8:** The merchant confirms the the final status to the shopper.

### **Payment Widget Form**&#x20;

&#x20;    **PayPal Payment Widget Request**

```
authentication.userId=8a8294174b7ecb28014b9699220015cc
authentication.password=sy6KJsT8
authentication.entityId=8a8294174b7ecb28014b9699220015ca
merchantTransactionId=customTxId
amount=4.00
currency=EUR
paymentType=PA
cart.items[0].name=iphone
cart.items[0].quantity=1
cart.items[0].price=4.00
customParameters[PAYPAL_PAYMENTREQUEST_0_INVNUM]=abcd-1234-abced-1234
customParameters[PAYPAL_USE_NEW_VERSION]=Yes

```

### **Server-to-Server Integration**

&#x20;   **PayPal Request**

```
authentication.userId=8a8294174b7ecb28014b9699220015cc
authentication.password=sy6KJsT8
authentication.entityId=8a8294174b7ecb28014b9699220015ca
merchantTransactionId=customTxId
amount=4.00
currency=EUR
paymentType=PA
cart.items[0].name=iphone
cart.items[0].quantity=1
cart.items[0].price=4.00
customParameters[PAYPAL_PAYMENTREQUEST_0_INVNUM]=abcd-1234-abced-1234
customParameters[PAYPAL_USE_NEW_VERSION]=Yes
paymentBrand=PAYPAL
virtualAccount.accountId=CHtest123@gmail.com
shopperResultUrl=https://docs.oppwa.com
```

&#x20;**Example PayPal Response**

```
{
  "id":"8a82944954bf044c0154cefc733f1943",
  "paymentType":"PA",
  "paymentBrand":"PAYPAL",
  "amount":"92.12",
  "currency":"EUR",
  "descriptor":"0397.9339.4338 OPP_Channel_old ",
  "merchantTransactionId":"x18m-AllParamsVATest",
  "result":{
    "code":"000.200.000",
    "description":"transaction pending"
  },
  "resultDetails":{
    "ConnectorTxID3":"bf044c0154cefc733f1943",
    "ConnectorTxID2":"8a829449",
    "ConnectorTxID1":"8a82944954bf044c0154cefc733f1943"
  },
  "redirect":{
    "url":"https://test.ppipe.net/connectors/simulator;jsessionid=33D90CE2F8086217BB2FA5CB32D00969.sbg-vm-con01",
    "parameters":[
      {
        "name":"useraction",
        "value":"commit"
      },
      {
        "name":"token",
        "value":"EC-4MJ483968G697473T"
      },
      {
        "name":"ndcid",
        "value":"8a8294174b7ecb28014b9699a3cf15d1_961bf86199ee49ec960fe5ccc44a28db"
      },
      {
        "name":"connector",
        "value":"PAYPAL"
      },
      {
        "name":"cmd",
        "value":"_express-checkout"
      }
    ]
  },
  "buildNumber":"c724840a1e553b5d2f76f2f03c9ffb260a72f91d@2016-05-17 14:47:50 +0000",
  "timestamp":"2016-05-20 16:25:31+0000",
  "ndc":"8a8294174b7ecb28014b9699a3cf15d1_961bf86199ee49ec960fe5ccc44a28db"
}
```

**Test Data**&#x20;

&#x20;For testing you may use the test account details listed below. It is important to note that the system has two test modes available to cause requests to be sent to the connector simulator or to the connector's own test platform, as required:

* testMode=EXTERNAL causes test transactions to be forwarded to the processor's test system for 'end-to-end' testing
* testMode=INTERNAL causes transactions to be sent to our simulators, which is useful when switching to the live endpoint for connectivity testing

{% hint style="info" %}
This test data is only working in testMode=INTERNAL. When using testMode=EXTERNAL, you will get a pending status response in 'error in asynchronous workflow (90); Previously pending transaction timed out (100.396.103)'.
{% endhint %}

### **How to check transaction activity**

After the shopper complete the transactions, PayPal displays those transactions in the Recent activity table located on the Summary page of your PayPal account.

**Step 1**: Log in to your PayPal account.

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MGhhO_TGqv2dyIVCgGT%2F-MGhkKNom_58t_iieo4i%2Fimage2017-7-12%2012_24_55.png?alt=media\&token=a5323039-2314-4b4d-b46c-33819c5fc3cc)

**Step 2**: Click the table heading "Activity"\
The Activity table is displayed and shows all transaction activity for the past 30 days.

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MGhhO_TGqv2dyIVCgGT%2F-MGhkPH4IrHuVl4L2SKO%2Fimage2017-7-12%2012_25_59.png?alt=media\&token=fdd5563c-cb46-48b7-aff5-b82cf3bde54e)

**Step 3**: Select options from the Active, All transactions, and All currencies menus to filter for a specific type of transaction activity. You can also use the search tool to filter activity. When viewing transaction activity, the status of payments can be:

* Completed: Transactions were successful, and funds were credited to your account.
* Cleared: Payments cleared senders' accounts, and funds were credited to your account.
* Uncleared: Payments have not cleared sender's accounts, and funds were not credited.


# Pulling our FX Rates

**Via API**

The following command authenticates you with your API credentials that you use for payment processing and returns the FX Rate upon successful authentication

**Command-line example with curl**

```
https://reports.primeiropay.com/fx?username=XXXXXXX&merchantId=XXXXXX&password=XXXXX
```

if the authentication fails, you will receive:

```
{
   "reason" : "INVALID_USER_AUTHENTICATION",
   "message" : "Failed to authenticate principal, user and/or password invalid"
}
```

If the authentication is successful you will be returned with the current valid FX Rates:

**Please note that only your settlement currency pair is being returned. If you wish to change your settlement currency, please contact your Account Manager.**

```
{
  "rate" : [ {
    "currency_pair" : "BRLUSD",
    "rate" : "3.795674",
    "valid_until" : "2015-01-15 15:00:00.0"
  } ]
}
```

{% file src="/files/-MGhfquobv7ViRjEPcAb" %}
Pulling FX Rates Json Request
{% endfile %}


# Going Live

1. You have to integrate with our test environment.

&#x20;  2\. Tests all payment methods that you want to use.

&#x20;  3\. If your test result as successfully we will check if everything is right

&#x20;  4\. if we find something missing we will help you to fix

&#x20;  5\. and when you fix everything we will send your live credentials


# Connect to SFTP

&#x20;To connect to our SFTP you will need a SFTP client. Your IT department can install one for you that is in accordance with your company policies.\
We recommend using FileZila **Client** as it\`s a well know, free and easy to use app. <https://filezilla-project.org/>

server: reporting.1pay.lu\
Port: 22

username and password is being provided by your Account Manager.

Upon successful connection you will be re-directed to your home directory in which you can pull reports from.

Video Example:

{% file src="/files/-MGhfREqw-Aaedz8XAnq" %}
Tutorial SFTP Login
{% endfile %}

{% file src="/files/-MGhfY4Jd-KVjKg\_cppS" %}
Tutorial SFTP Login with Key
{% endfile %}


# Disputes

All Brazilian transactions disputes will be informed in a report called Disputes Report.

This report will be placed in the merchant’s home folder in our SFTP (same folder merchant\`s already receive other reports) and will contain all information about the disputes, including UniqueID, merchant transaction id,  amount, dispute reason, dispute expiry date and a status – Open, Win, Lose.

|   | Arquivo                                       | Modificado                      |
| - | --------------------------------------------- | ------------------------------- |
|   | EXAMPLE\_\_DISPUTES\_\_REPORT\_2019-12-23.csv | dez 24, 2019 by Fernando Garcia |

{% file src="/files/-MGy8-CZuWK9C2K2ST63" %}
EXAMPLE\_DISPUTES\_REPORT\_2019-12-23.CSV
{% endfile %}

| **Name**                       | **Description**                                                                       | **Format**                              | **Example**                              |
| ------------------------------ | ------------------------------------------------------------------------------------- | --------------------------------------- | ---------------------------------------- |
| Record Type                    | The type of the record line. Can be Chargeback Second Chargeback, Chargeback Reversal | AN \[a-zA-Z0-9\_]                       | Chargeback                               |
| Psp Reference                  | Unique id of the transaction related to the dispute                                   | AN \[a-zA-Z0-9\_]                       | 8a83948355021710015507ccee0869a1         |
| Merchant Reference             | Reference for the transaction sent by merchant                                        | AN \[a-zA-Z0-9\_]                       | c4345h534aVwJE                           |
| Payment Method                 | Brand of the card                                                                     | AN \[a-zA-Z0-9\_]                       | VISA                                     |
| Payument Date                  | Date of when the transaction happened in UTC                                          | MM/DD/YYYY HH:MM:DD timezone (+/-HH:MM) | 12/23/2019 16:28:41 UTC(+00:00)          |
| CB Notification Case Number    | Identification of the dispute at the acquirer                                         | AN \[a-zA-Z0-9\_]                       | 2791QAT326851                            |
| Reason Code                    | Reason code of the dispute                                                            | NNN.NNN.NNN                             | 000.100.222                              |
| Dispute Reason                 | Description of the reason code                                                        | AN \[a-zA-Z0-9\_]                       | Transaction Not Recognized By Cardholder |
| Payment Amount                 | Amount of original transaction                                                        | N13\[0- 9]{1,10}\\.\[0 -9]{2}           | 54.12                                    |
| Payment Currency               | Currency of the original transaction using ISO4217                                    | A3 \[a-zA-Z]                            | BRL                                      |
| Dispute amount                 | Amount of the dispute                                                                 | N13\[0- 9]{1,10}\\.\[0 -9]{2}           | 54.12                                    |
| Dispute Currency               | Currency of the original transaction using ISO4217                                    | A3 \[a-zA-Z]                            | BRL                                      |
| Psp Notified At                | Date of when PrimeiroPay was notified                                                 | MM/DD/YYYY                              | 12/23/2019                               |
| Connector Tx Id                | Transaction ID of the acquirer                                                        | AN \[a-zA-Z0-9\_]                       | 10551804345FV948MMVD                     |
| Shopper Name                   | Shopper name informed in the original transaction                                     | AN \[a-zA-Z0-9\_]                       | José Silva                               |
| Shopper email                  | Shopper email informed in the original transaction                                    | AN \[a-zA-Z0-9\_]                       | <josesilva@provider.com>                 |
| Shopper IP                     | Shopper IP informed in the original transaction                                       | AN \[a-zA-Z0-9\_]                       | 234.235.124.243                          |
| Shopper Country                | Shopper Country informed in the original transaction                                  | AN \[a-zA-Z]                            | BR                                       |
| Card Bin                       | First 6 digits of the card                                                            | N6\[0- 9]                               | 411111                                   |
| ThreeD Directory Response      | Acqurer response for 3d directory, when available                                     | AN \[a-zA-Z0-9\_]                       | A                                        |
| ThreeD Authentication Response | Acqurer response for 3d authentication, when available                                | AN \[a-zA-Z0-9\_]                       | Y                                        |
| Cvc2 Response                  | Acqurer response for CVC2 matching, when available                                    | AN \[a-zA-Z0-9\_]                       | Y                                        |
| Avs Response                   | Cvc2 mathcing Response                                                                | N2\[0- 9]{1,10}\\.\[0 -9]{2}            | 12                                       |
| Dispute Expiry                 | Date and time of when the dispute will be open and accepting defense materials.       | MM/DD/YYYY HH:MM:DD timezone (+/-HH:MM) | 12/30/2019 16:28:41 UTC(+00:00)          |
| Final Outcome                  | Open for new rtransactions, Win or Lose for when you win or lose a dispute.           | AN \[a-zA-Z0-9\_]                       | Win                                      |

**Sending defense documents**

Merchants can send their dispute documents by uploading the files to the folder /Disputes in your SFTP. We accept **one file** per transaction in **PDF** format with a limit of **7 MB**.

The file has to use the following naming specification:

**Uniqueid\_\[optional merchant naming]**

Example: For a merchant that wants to add a date and their merchantID, this would be the file name:

8a83948355021710015507ccee0869a1\_2019-11-01\_merchantID1224.pdf

For more information on how to access our SFTP, contact your Account Manager.


# Dispute notifications via webhooks

PrimeiroPay sends dispute information via webhooks to inform the merchant about the current status of the dispute.

The merchant shall inform a listener HTTPS URL to its account manager in order to set up this feature.

When your service receives a webhook notification, it must return a **200** HTTP status code. Otherwise, the webhook service considers the notification delivery as failed. PrimeiroPay currently does not retry failed webhooks.

**Example:**&#x20;

```
{
  "uniqueId":"777777777777777",
  "merchantId":"8acda4cb6193d56a0161949d31de0dda",
  "merchantTransactionId":"1331837",
  "amount":1762.0,
  "caseNumber":"26379847",
  "chargebackCountRequest":1,
  "disputeEndDateTime":"2019-10-09 21:00:00.000",
  "notificationDateTime":"2019-10-02 11:00:00.000",
  "status":"WIN",
  "acquirerReasonCodeId":77,
  "adyenMerchantRefId":"4147",
  "reasonCode":"000.100.222",
  "disputeReason":"Transaction Not Recognized By Cardholder",
  "brand":"MASTERCARD",
  "brandReasonCode":"4837"
}
```

**Frequency**

Whenever the “status” changes a webhook is being sent to the listener URL.\
A dispute notification can have the following status:\
*OPEN*\
*WIN*\
*LOSE*\
\
**The merchant receives therefor maximum three notifications for a single transaction**. PrimeiroPay currently does not retry failed webhooks.

| **Name**               | **Description**                                                                                     | **Format**                    | **Example**                              |
| ---------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------- |
| UniqueId               | Unique Identifier for PrimeiroPay                                                                   | AN \[a-zA-Z0-9\_]             | 8a83948355021710015507ccee0869a1         |
| merchantId             | Unique Identifier of the merchant for PrimeiroPay                                                   | AN \[a-zA-Z0-9\_]             | 8a83948355021710015507ccee0869a1         |
| merchantTransactionId  | Unique id of the transaction related to the dispute, if connected via Adyen it is the PSP Reference | AN \[a-zA-Z0-9\_]             | 8a83948355021710015507ccee0869a1         |
| amount                 | Amount of original transaction                                                                      | N13\[0- 9]{1,10}\\.\[0 -9]{2} | 54.12                                    |
| caseNumber             | Identification of the dispute at the acquirer                                                       | AN \[a-zA-Z0-9\_]             | 2791QAT326851                            |
| chargebackCountRequest | Indicates how many chargebacks were issued for the same transaction                                 | N2\[0- 9]{1,10}               | 1                                        |
| disputeEndDateTime     | Date and time of until the dispute will be open and accepting defense materials.                    | YYYY-MM-DD HH:MM:SS.sss       | 2019-10-09 21:00:00.000                  |
| notificationDateTime   | Date and time of when the notification was received by PrimeiroPay                                  | YYYY-MM-DD HH:MM:SS.sss       | 2019-10-09 21:00:00.000                  |
| Status                 | Open for new transactions, Win or Lose for when you win or lose a dispute.                          | AN \[a-zA-Z0-9\_]             | Win                                      |
| acquirerReasonCodeId   | Description of the reason code                                                                      | N3\[0- 9]{1,10}               | 77                                       |
| adyenMerchantRefId     | Merchant Reference ID from Adyen if Merchant is connected through Adyen to PrimeiroPay              | AN \[a-zA-Z0-9\_]             | 4147                                     |
| reasonCode             | Result codes as listed: <https://developers.primeiropay.com/result-codes>                           | AN \[NNN.NNN.NNN]             | 000.100.222                              |
| disputeReason          | Description/reason of the dispute, according to it’s reason code.                                   | AN \[a-zA-Z0-9\_]             | Transaction Not Recognized By Cardholder |
| brand                  | Card Brand of the dispute                                                                           | AN \[a-zA-Z0-9\_]             | MASTERCARD                               |
| brandReasonCode        | Reason code using Brand’s specification code.                                                       | AN \[a-zA-Z0-9\_]             | 4837                                     |


# Disputes guides

1. To connect to our SFTP, you will first need to contact your Account Manager to provide you with a host, username, and password.

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MKqiZToefISymE2KJ24%2F-MKqpx8JQksS_SexhhzW%2Fef2a394b-d64d-40b1-bc2e-6454a1da57d8.png?alt=media\&token=291b2057-4e84-41fb-b922-814fb88355d9)

2\. Using the credentials that were created, connect to the SFTP and there will be all your reports, including the disputes report.![](blob:https://primeiropay.atlassian.net/1ffebcfd-90a1-4dea-a91a-45c4b178d3e1#media-blob-url=true\&id=20088b86-3d4c-471f-b1ce-6fa4ce8f8db1\&collection=contentId-1055326213\&contextId=1055326213\&mimeType=image%2Fpng\&name=image-20200409-204908.png\&size=10352\&width=807\&height=28)

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MKqiZToefISymE2KJ24%2F-MKqq1aIzEIJfCWol8yJ%2F1ffebcfd-90a1-4dea-a91a-45c4b178d3e1.png?alt=media\&token=1e9873bc-9a39-4b96-8a97-178763506a76)

3\. Also you will find a folder named 'DISPUTES': Inside the folder, you will see all files that are uploaded on a daily basis with the following filename structure:

Name of Merchant \_Name of Report ( Disputes)\_ Date when the file was received

4\. Opening the file will display the complete detailed information regarding the disputed transaction: ![](blob:https://primeiropay.atlassian.net/fa41e9f3-3f3b-4845-990d-20e4f41f3be9#media-blob-url=true\&id=dcb4aacf-597d-4009-b139-b183a69d7e26\&collection=contentId-1055326213\&contextId=1055326213\&mimeType=image%2Fpng\&name=image-20200409-205044.png\&size=50547\&width=756\&height=71)

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MKqiZToefISymE2KJ24%2F-MKqq6MgSZ5OzdzUQ1yS%2Ffa41e9f3-3f3b-4845-990d-20e4f41f3be9.png?alt=media\&token=1fc3d028-a9d4-49fa-9e31-e41357cd0e7f)

5\. Basing on the information provided in this file, it’s now required to build your defense case collecting all evidence that supports your case in a pdf (*7 MB size limit*) and include in the file’s name your *psp reference*. Down below is a list of documents that are needed to dispute a case:&#x20;

* 1 - Receipt;
* 2 - All shopper details - Full name, CPF number, email, phone number, address, etc.;
* 3 - Invoice;
* 4 - Copy of Order;
* 5 - Proof of service or product delivery;
* 6 - Screenshot with the transaction details;
* 7 - Shopper's letter assuming he actually made the transaction.

6\. List fully checked? Now, as a final step, upload your PDF to the folder Disputes: home > disputes. Tha file name has to start with the transaction uniqueid: **Uniqueid\_\[optional merchant naming]**![](blob:https://primeiropay.atlassian.net/e215e6f7-ee7b-46e8-8f16-2acb618852bf#media-blob-url=true\&id=4ed4e0db-375b-4793-a982-df17c3208a0f\&collection=contentId-1055326213\&contextId=1055326213\&mimeType=image%2Fpng\&name=image-20200409-204706.png\&size=8214\&width=807\&height=33)

![](https://1991843971-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGcOwWYO42hhJYXrYx1%2F-MKqiZToefISymE2KJ24%2F-MKqqA0Z-Jb0mk2Tj2Qt%2Fe215e6f7-ee7b-46e8-8f16-2acb618852bf.png?alt=media\&token=c80f5132-72b4-41df-880f-17d495563304)

7\. As the cases get analyzed and closed, the outcome of the dispute will be found in the list of transactions in the same spreadsheet (Dispute Report), underneath a column named: Final Outcome.\ <br>

**Easy, right? Here is some additional information:**

\
• Our acquirer takes up 90 days to send us a feedback on the outcome.\
• Your defenses will always have one of the following statuses:

\
**Open:** chargeback is still pending to be disputed (7 days to defend a case).\
**Win:** Merchant won the defense, the debit won't be charged from your balance.\
**Lose:** The shopper will pay the debit, which will be settled and can be found in the settlement report.


# Force Result Code

in our **TEST ENVIRONMENT** you can use this parameter to force a result and see how your system will handle.

```
-d "customParameters[forceResultCode]={any result code}"
```

you can check all results codes here: [**Result Code**](https://developers.primeiropay.com/result-codes)**.**


# API Parameters Reference

### Introduction <a href="#introduction" id="introduction"></a>

‌

This reference section provides you with a complete and in-depth description of the PrimeiroPayment Platform API.‌

### ​Hosts​ <a href="#hosts" id="hosts"></a>

‌

* Test: <https://test.oppwa.com/>
* Live: <https://oppwa.com/>

‌

### ​Security / Authentication​ <a href="#security-authentication" id="security-authentication"></a>

‌

All requests must be sent over SSL‌

All requests are authenticated against an Authorization Bearer header with an access token. All the other data parameters are sent as body parameters, see [Authentication Parameters](https://developers.primeiropay.com/api-parameters-reference#authentication) for more information.‌

### ​Throttling​ <a href="#throttling" id="throttling"></a>

‌

Throttling is the process of limiting the number of requests submitted to a given operation in a given amount of time. Throttling protects the web service from being overwhelmed with requests and ensures providing a healthy web service.‌

Following throttling values has been configured:‌

#### Live system <a href="#live-system" id="live-system"></a>

‌

&#x20;Show throttling details‌

#### Test system <a href="#test-system" id="test-system"></a>

‌

&#x20;Show throttling details‌

Requests which will be affected by throttling, will be rejected with following return code:

```
{
   "buildNumber":"b297e8ec4aa0888454578e292c67546d4c6a5c28@2018-08-30 06:31:46 +****",
   "id":"8ac9a4a8658afc790165a3f0e436198d",
   "ndc":"8acda4c9635ea2d90163636f0a462510_ebb07f3e26e942908d6eeed03a813237",
   "result":{
      "code":"800.120.100",
      "description":"Too many requests. Please try again later."
   },
   "timestamp":"2018-09-04 09:42:33+0000"
}
```

‌

### ​Versioning​ <a href="#versioning" id="versioning"></a>

‌

The API version is indicated in the request URL e.g. /v1/payments indicates version 1.‌

All changes made to the API are backwards compatible, hence any major features that are released, that would otherwise break existing implementations, will be released using a new version.‌

### ​Encoding​ <a href="#encoding" id="encoding"></a>

‌

Our system expects data to be sent encoded in UTF-8.‌

Using this Content-Type header can help:‌

`application/x-www-form-urlencoded; charset=UTF-8`‌

### ​HTTP Status Codes​ <a href="#http-status-codes" id="http-status-codes"></a>

‌

For each request you send to our API the `HTTP status code` of the response will already tell you the basic result.‌

200 - successful request‌

307 - temporary redirect‌

400 - bad request. This might either point to e.g. invalid parameters or values sent. It's also returned if the payment failed e.g. because the acquirer declined.‌

401 - invalid authorization header provided‌

403 - invalid access token provided‌

404 - requested resource or endpoint is not found. I.e. endpoint/url doesn't exist. This can also be caused by typos like POST /v1/paym**ne**ts instead of payments or wrong IDs like GET /v1/payments/{id} where no payment with {id} exists.‌

For payments you'll want more fine grained information to find out why a payment failed. You're getting this information in the [result codes](https://developers.primeiropay.com/untitled).‌

### ​Testing​ <a href="#testing" id="testing"></a>

‌

It is important to note that we have two test modes available to cause requests to be sent to our connector simulator or to the connector's own test platform, as required:‌

* `testMode=EXTERNAL` causes test transactions to be forwarded to the processor's test system for 'end-to-end' testing
* `testMode=INTERNAL` causes transactions to be sent to our simulators, which is useful when switching to the live endpoint for connectivity testing.

‌

If no testMode parameter is sent, `testMode=INTERNAL` is the default behaviour‌

#### ​Credit Card Test Accounts​ <a href="#credit-card-test-accounts" id="credit-card-test-accounts"></a>

| Brand  | Number                                                  | CVV          | Expiry Date          |
| ------ | ------------------------------------------------------- | ------------ | -------------------- |
| VISA   | 4200000000000000 (no 3D) 4711100000000000 (3D enrolled) | any 3 digits | any date after today |
| MASTER | 5454545454545454 (no 3D) 5212345678901234 (3D enrolled) | any 3 digits | any date after today |
| AMEX   | 377777777777770 (no 3D) 375987000000005 (3D enrolled)   | any 4 digits | any date after today |

‌

#### Test Bank Accounts (SEPA) <a href="#test-bank-accounts-sepa" id="test-bank-accounts-sepa"></a>

| Country      | IBAN                     | BIC         |
| ------------ | ------------------------ | ----------- |
| Austria (AT) | AT152011128161647502     | GIBAATWWXXX |
| Germany (DE) | DE23100000001234567890   | MARKDEF1100 |
| Spain (ES)   | ES9121000418450200051332 | CAIXESBBXXX |

‌

This reference lists all the PrimeiroPayment Platform parameters, grouped by their data structures.‌

### Basic Payment <a href="#basic-payment" id="basic-payment"></a>

| Parameter                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Format                                     | Required    |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------- |
| amount                      | Indicates the amount of the payment request. The dot is used as decimal separator. The amount is the only amount value which is processing relevant. All other amount declarations like taxAmount or shipping.cost are already included.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | N10.N2 \[0-9]{1,10}(\\.\[0-9]{2})?         | Required    |
| taxAmount                   | Indicates the tax amount of the payment request. The dot is used as decimal separator.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | N10.N2 \[0-9]{1,10}(\\.\[0-9]{2})?         | Conditional |
| currency                    | The currency code of the payment request's amount ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | A3 \[A-Z]{3}                               | Required    |
| paymentBrand                | The brand specifies the method of payment for the request. This is optional if you want to use brand detection for credit cards, if not then it is mandatory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | AN32 \[a-zA-Z0-9\_] {1,32}                 | Conditional |
| paymentType                 | <p>The payment type for the request. You can send payment requests with one of the following types:</p><ul><li><strong>PA</strong>, Preauthorization: A stand-alone authorisation that will also trigger optional risk management and validation. A Capture (CP) with reference to the Preauthorisation (PA) will confirm the payment..</li><li><strong>DB</strong>, Debit: Debits the account of the end customer and credits the merchant account.</li><li><strong>CD</strong>, Credit: Credits the account of the end customer and debits the merchant account.</li><li><strong>CP</strong>, Capture: Captures a preauthorized (PA) amount.</li><li><strong>RV</strong>, Reversal: Reverses an already processed Preauthorization (PA), Debit (DB) or Credit (CD) transaction. As a consequence, the end customer will never see any booking on his statement. A Reversal is only possible until a connector specific cut-off time. Some connectors don't support Reversals.</li><li><strong>RF</strong>, Refund: Credits the account of the end customer with a reference to a prior Debit (DB) or Credit (CD) transaction. The end customer will always see two bookings on his statement. Some connectors do not support Refunds.</li></ul> | A2                                         | Required    |
| overridePaymentType\[brand] | The payment type can be overriden for specific brands, for example: overridePaymentType\[BOLETO]=PA overridePaymentType\[KLARNA\_INVOICE]=PA In such cases, the default payment type will be the one defined in paymentType parameter and every brand defined in overridePaymentType will have its own payment type. **This parameter is only accepted during the checkout creation.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | brand: AN32 \[a-zA-Z0-9\_]{1,32} value: A2 | Optional    |
| descriptor                  | Can be used to populate all or part of the Merchant Name descriptor, which often appears on the first line of the shopper's statement. The full use of this field depends on the Merchant Account configuration. NOTE: `merchant.name` can override any data sent in this field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | AN127 \[\s\S]{1,127}                       | Optional    |
| merchantTransactionId       | Merchant-provided reference number, should be unique for your transactions. Some receivers require this ID. This identifier is often used for reconciliation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | AN255 \[\s\S]{8,255}                       | Conditional |
| merchantInvoiceId           | Merchant-provided invoice number, should be unique for your transactions. This identifier is not sent onwards.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | AN255 \[\s\S]{8,255}                       | Optional    |
| merchantMemo                | Merchant-provided additional information. The information provided is not transaction processing relevant. It will appear in reporting only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | AN255 \[\s\S]{8,255}                       | Optional    |
| transactionCategory         | <p>The category of the transaction, possible values are:</p><ul><li>EC - eCommerce</li><li>MO - Mail order</li><li>TO - Telephone order</li><li>RC - Recurring</li><li>IN - Installment</li><li>PO - pos</li><li>PM - mpos</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | AN32 \[a-zA-Z0-9]{0,32}                    | Optional    |

‌

### Authentication <a href="#authentication" id="authentication"></a>

‌

To make REST API calls, include the access token in the Authorization header with the Bearer authentication scheme.

| Parameter / Header                   | Description                                                                                                                                                                                                          | Format             | Required    |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------- |
| entityId                             | The entity required to authorize the request. This should be the channel entity identifier. In case channel dispatching is activated then it should be the merchant entity identifier.                               | AN32 \[a-f0-9]{32} | Conditional |
| Authorization Bearer \<access-token> | Authorization header with Bearer authentication scheme. Access token can be taken from the backend UI under Administration > Account data > Merchant / Channel Info only if you have specific administration rights. | Header             | Required    |

‌

### Card Account <a href="#card-account" id="card-account"></a>

‌

The card data structure holds all information regarding a credit or debit card account.

| Parameter        | Description                            | Format                 | Required    |
| ---------------- | -------------------------------------- | ---------------------- | ----------- |
| card.holder      | Holder of the credit card account      | A128 {3,128}           | Optional    |
| card.number      | The PAN or account number of the card. | N19 \[0-9]{12,19}      | Required    |
| card.expiryMonth | The expiry month of the card.          | N2 (0\[1-9]\|1\[0-2])  | Required    |
| card.expiryYear  | The expiry year of the card.           | N4 (19\|20)(\[0-9]{2}) | Required    |
| card.cvv         | The card security code or CVV          | N4 \[0-9]{3,4}         | Conditional |

‌

### Apple Pay <a href="#apple-pay" id="apple-pay"></a>

‌

There are two possible APIs for Apple Pay:‌

#### Apple Pay with encrypted payment token <a href="#apple-pay-with-encrypted-payment-token" id="apple-pay-with-encrypted-payment-token"></a>

‌

You can send the encrypted payment token as-is. We will do the decryption and process the transaction.

| Parameter             | Description                                  | Format           | Required |
| --------------------- | -------------------------------------------- | ---------------- | -------- |
| applePay.paymentToken | The encrypted payment token created by Apple | Defined by Apple | Required |

‌

#### Apple Pay with decrypted card information <a href="#apple-pay-with-decrypted-card-information" id="apple-pay-with-decrypted-card-information"></a>

‌

You can do the decryption by yourself and send us the decrypted card information with the usual card API: card.number, card.expiryMonth, card.expiryYear, threeDSecure.verificationId, threeDSecure.eci, and the following parameter:

| Parameter       | Description                       | Format   | Required |
| --------------- | --------------------------------- | -------- | -------- |
| applePay.source | Indicates the source of Apple Pay | web\|app | Required |

‌

### Virtual Account <a href="#virtual-account" id="virtual-account"></a>

‌

The virtual account data structure is used to send account-based payments, e.g. PAYPAL.

| Parameter                | Description                                      | Format               | Required |
| ------------------------ | ------------------------------------------------ | -------------------- | -------- |
| virtualAccount.accountId | The identifier of the shopper's virtual account. | AN100 \[\s\S]{1,100} | Required |

‌

### Bank Account <a href="#bank-account" id="bank-account"></a>

‌

The bank account data structure holds all the information that specifies a bank account. This is used for bank-account based payments, e.g. direct debits, SEPA and bank transfers. Collecting money from the shopper's bank account generally requires his approval. SEPA specific parameters - bankAccount.mandate.id, bankAccount.mandate.dateOfSignature,transactionDueDate are not used in the risk checks.

| Parameter                           | Description                                                                                                                | Format                                                                           | Required    |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------- |
| bankAccount.holder                  | Holder of the bank account                                                                                                 | AN128 {4,128}                                                                    | Required    |
| bankAccount.bankName                | The name of the bank which holds the account.                                                                              | AN255 \[\s\S]{1,255}                                                             | Conditional |
| bankAccount.number                  | The account number of the bank account. Either the number or the iban are required.                                        | AN64 \[a-zA-Z0-9]{3,64}                                                          | Conditional |
| bankAccount.iban                    | The IBAN (International Bank Account Number) associated with the bank account. Either the number or the iban are required. | AN31 \[a-zA-Z]{2}\[0-9]{2}\[a-zA-Z0-9]{11,27}                                    | Conditional |
| bankAccount.bankCode                | The code associated with the bank account. Either the bankCode or the bic are required.                                    | AN12 \[a-zA-Z0-9]{1,12}                                                          | Conditional |
| bankAccount.bic                     | The BIC (Bank Identifier Code (SWIFT)) number of the bank account. Either the bankCode or the bic are required.            | AN11 \[a-zA-Z0-9]{8}\|\[a-zA-Z0-9]{11}                                           | Conditional |
| bankAccount.country                 | The country code of the bank account ([ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1)).                             | AN2 \[a-zA-Z]{2}                                                                 | Conditional |
| bankAccount.mandate.id              | The id of the mandate for direct debit.                                                                                    | AN256 \[a-zA-Z\\-]{0,256}                                                        | Conditional |
| bankAccount.mandate.dateOfSignature | The date the direct debit mandate was signed.                                                                              | AN10 {19\|20)(\[0-9]{2})-(0\[1-9]\|1\[0-2])-(0\[1-9]\|1\[0-9]\|2\[0-9]\|3\[0-1]} | Conditional |
| transactionDueDate                  | The due date of the transaction of the direct debit.                                                                       | AN10 {19\|20)(\[0-9]{2})-(0\[1-9]\|1\[0-2])-(0\[1-9]\|1\[0-9]\|2\[0-9]\|3\[0-1]} | Conditional |

‌

### Customer <a href="#customer" id="customer"></a>

‌

The customer data structure holds information about the customer/shopper such as their name, identification documents and contact details. The customer fields serve mixed purposes: On the one hand they are just for you to store information on your customers, but on the other hand they are also used and sometimes required for risk management and payment providers that require ID/mandate information. These use cases are noted in the parameters' descriptions.

| Parameter                         | Description                                                                                                                                                                                                                                                                                                                      | Format                                                                           | Required    |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------- |
| customer.merchantCustomerId       | An identifier for this customer. Typically this is the ID that identifies the shopper in the shop's system.                                                                                                                                                                                                                      | AN255 \[\s\S]{1,255}                                                             | Optional    |
| customer.givenName                | The first name or given name of the customer. Required if you send in any other customer parameters, also required for some risk checks and payment providers. Will be truncated after 48 characters                                                                                                                             | AN \[\s\S]                                                                       | Conditional |
| customer.middleName               | The middle name of the customer.                                                                                                                                                                                                                                                                                                 | AN50 \[\s\S]{2,50}                                                               | Optional    |
| customer.surname                  | The last name or surname of the customer. Required if you send in any other customer parameters, also required for some risk checks and payment providers. Will be truncated after 48 characters                                                                                                                                 | AN \[\s\S]                                                                       | Conditional |
| customer.sex                      | Sex of the shopper, 'M' for male or 'F' for female                                                                                                                                                                                                                                                                               | A1 M\|F                                                                          | Optional    |
| customer.birthDate                | The birth day of the customer in the format yyyy-MM-dd, e.g. 1970-02-17                                                                                                                                                                                                                                                          | AN10 {19\|20)(\[0-9]{2})-(0\[1-9]\|1\[0-2])-(0\[1-9]\|1\[0-9]\|2\[0-9]\|3\[0-1]} | Optional    |
| customer.phone                    | The customer's phone number. Required for some risk checks.                                                                                                                                                                                                                                                                      | AN25 \[+0-9]\[0-9 \\.()/-]{7,25}                                                 | Optional    |
| customer.mobile                   | The customer's mobile number. Required for some risk checks.                                                                                                                                                                                                                                                                     | AN25 \[+0-9]\[0-9 \\.()/-]{5,25}                                                 | Optional    |
| customer.workPhone                | The customer's phone number. Required for some risk checks.                                                                                                                                                                                                                                                                      | AN25 \[\s\S]{1,25}                                                               | Optional    |
| customer.email                    | The customer's email address. Required for some risk checks and transmission of direct debit mandates.                                                                                                                                                                                                                           | AN128 \[\s\S]{6,128}                                                             | Optional    |
| customer.companyName              | The customer's company name.                                                                                                                                                                                                                                                                                                     | AN60 \[\s\S]{1,60}                                                               | Optional    |
| customer.identificationDocType    | The type of identification document for the customer. Can be one of these three values: IDCARD, PASSPORT, TAXSTATEMENT. If this parameter is sent then customer.identificationDocId must be also sent. It is also mandatory for certain payment types (e.g. Boleto).                                                             | A12 \[\s\S]                                                                      | Conditional |
| customer.identificationDocId      | The identifier of the identification document for the customer. If this parameter is sent then customer.identificationDocType must also be sent. It is also mandatory for certain payment types (e.g. Boleto).                                                                                                                   | AN64 \[\s\S]{8,64}                                                               | Conditional |
| customer.ip                       | The customer's IP address.                                                                                                                                                                                                                                                                                                       | AN255 \[\s\S]{1,255}                                                             | Optional    |
| customer.browserFingerprint.id    | The reference to the fingerprint of the shopper's browser, in most cases provided by some JavaScript library.                                                                                                                                                                                                                    | \[\s\S]{1,255}                                                                   | Optional    |
| customer.browserFingerprint.value | The actual fingerprint value of the shopper's browser                                                                                                                                                                                                                                                                            | \[\s\S]{1,4096}                                                                  | Optional    |
| customer.browser.acceptHeader     | Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. Mandatory for 3DS v2.                                                                                                                                                                                                       | \[\s\S]{1,2048}                                                                  | Conditional |
| customer.browser.language         | Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property. Mandatory for 3DS v2.                                                                                                                                                                                               | \[\s\S]{1,8}                                                                     | Conditional |
| ​Content                          | ​Content                                                                                                                                                                                                                                                                                                                         | ​Content                                                                         | ​Content    |
| customer.browser.screenHeight     | Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property. Mandatory for 3DS v2.                                                                                                                                                                                                      | \[\s\S]{1,6}                                                                     | Conditional |
| customer.browser.screenWidth      | Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property. Mandatory for 3DS v2.                                                                                                                                                                                                        | \[\s\S]{1,6}                                                                     | Conditional |
| customer.browser.timezone         | Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead Mandatory for 3DS v2.                                                                                                                           | \[\s\S]{1,5}                                                                     | Conditional |
| customer.browser.userAgent        | Exact content of the HTTP user-agent header. Mandatory for 3DS v2.                                                                                                                                                                                                                                                               | \[\s\S]{1,2048}                                                                  | Conditional |
| customer.browser.javaEnabled      | Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property. Mandatory for 3DS v2.                                                                                                                                                                  | true/false                                                                       | Conditional |
| customer.browser.screenColorDepth | Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property.                                                                                                                                                          | N2 \[0-9]{1,2}                                                                   | Optional    |
| customer.browser.challengeWindow  | Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width x height in pixels of the window displayed in the Cardholder browser window. | N2                                                                               | Optional    |
| customer.browser.deviceId         | Value representing the customer browser device id.                                                                                                                                                                                                                                                                               | AN32 \[\s\S]{1,32}                                                               | Optional    |
| customer.status                   | A status of the customer. Currently two options- NEW, EXISTING.                                                                                                                                                                                                                                                                  | A9 \[\s\S]{1,255}                                                                | Optional    |

‌

### Shipping customer <a href="#shipping-customer" id="shipping-customer"></a>

‌

The shipping customer has the same fields than the billing customer, just as part of the shipping entity. That way you can ship to an entirely different customer.

| Parameter            | Description                                                                                                                            | Format                      | Required |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------- |
| shipping.customer.\* | All the fields that are available under customer except shipping.customer.browserFingerprint.\* and shipping.customer.browser.deviceId | Same as for customer fields | Optional |

‌

### Billing Address <a href="#billing-address" id="billing-address"></a>

‌

The billing address holds the address of the customer. Information sent in the billing address data structure can optionally be used for risk checks such as AVS for card processing.

| Parameter                | Description                                                                                                                                                                                              | Format                     | Required    |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----------- |
| billing.street1          | The door number, floor, building number, building name, and/or street name of the billing address Mandatory for 3D Secure v2.                                                                            | AN100 \[\s\S]{1,100}       | Conditional |
| billing.street2          | The adjoining road or locality (if required) of the billing address The combination of billing.street1 and billing.street2 can't contain numbers only, it should also include characters.                | AN100 \[\s\S]{1,100}       | Conditional |
| billing.houseNumber1     | Primary house number (door number or building number) of the billing address. If present, then billing.street1 is assumed to contain only the name of the street. Also, billing.street2 will be ignored. | AN100 \[\s\S]{1,100}       | Optional    |
| billing.houseNumber2     | Secondary house number (floor, building name) of the billing address. Used when more addresses are bundled to a same primary house number. If present, billing.houseNumber1 is also mandatory.           | AN100 \[\s\S]{1,100}       | Optional    |
| billing.city             | The town, district or city of the billing address Mandatory for 3D Secure v2.                                                                                                                            | AN80 \[\s\S]{1,80}         | Conditional |
| billing.state            | The county, state or region of the billing address                                                                                                                                                       | AN50 \[a-zA-Z0-9\\.]{1,50} | Conditional |
| billing.postcode         | The postal code or zip code of the billing address Mandatory for 3D Secure v2.                                                                                                                           | AN30 \[A-Za-z0-9]{1,30}    | Conditional |
| billing.country          | The country of the billing address ([ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1)) Mandatory for 3D Secure v2.                                                                                  | A2 \[A-Z]{2}               | Conditional |
| billing.normalized       | The normalized shipping address.                                                                                                                                                                         | AN255 \[\s\S]{1,255}       | Optional    |
| billing.validationStatus | Indicates whether a address got validated and normalized address got confirmed by the consumer                                                                                                           | AN255 \[\s\S]{1,255}       | Optional    |

‌

### Shipping Address <a href="#shipping-address" id="shipping-address"></a>

‌

The shipping address holds the location and recipient of ordered goods. This can be used for risk processing or logistics.

| Parameter                     | Description                                                                                                                                                                                                                                                                 | Format                                                                           | Required    |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------- |
| shipping.street1              | The door number, floor, building number, building name, and/or street name of the shipping address                                                                                                                                                                          | AN100 \[\s\S]{1,100}                                                             | Conditional |
| shipping.street2              | The adjoining road or locality (if required) of the shipping address                                                                                                                                                                                                        | AN100 \[\s\S]{1,100}                                                             | Conditional |
| shipping.houseNumber1         | Primary house number (door number or building number) of the shipping address. If present, then shipping.street1 is assumed to contain only the name of the street. Also, shipping.street2 will be ignored.                                                                 | AN100 \[\s\S]{1,100}                                                             | Optional    |
| shipping.houseNumber2         | Secondary house number of the shipping address (floor, building name). Used when more addresses are bundled to a same primary house number. If present, shipping.houseNumber1 is also mandatory.                                                                            | AN100 \[\s\S]{1,100}                                                             | Optional    |
| shipping.city                 | The town, district or city of the shipping address                                                                                                                                                                                                                          | AN80 \[a-zA-Z]{1,80}                                                             | Conditional |
| shipping.state                | The county, state or region of the shipping address                                                                                                                                                                                                                         | AN50 \[a-zA-Z0-9\\.]{1,50}                                                       | Conditional |
| shipping.postcode             | The postal code or zip code of the shipping address                                                                                                                                                                                                                         | AN30 \[A-Za-z0-9]{1,30}                                                          | Conditional |
| shipping.country              | The country of the shipping address ([ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1))                                                                                                                                                                                | A2 \[A-Za-z]{2}                                                                  | Conditional |
| shipping.method               | Method of the shipping. One of the options: LOWEST\_COST, CARRIER\_DESIGNATED\_BY\_CUSTOMER, ELECTRONIC\_DELIVERY, GROUND, INTERNATIONAL, MILITARY, NEXT\_DAY\_OVERNIGHT, OTHER, STORE\_PICKUP, SAME\_DAY\_SERVICE, TWO\_DAY\_SERVICE, THREE\_DAY\_SERVICE, PUDO, EXPEDITED | AN30 \[A-Z\_]{5,30}                                                              | Conditional |
| shipping.cost                 | The total amount of the shipping costs.                                                                                                                                                                                                                                     | N13 \[0-9]{1,10}\\.\[0-9]{2}                                                     | Conditional |
| shipping.comment              | A comment for the shipping                                                                                                                                                                                                                                                  | AN160 \[\s\S]{1,160}                                                             | Conditional |
| shipping.expectedDate         | The expected delivery date                                                                                                                                                                                                                                                  | AN10 {19\|20)(\[0-9]{2})-(0\[1-9]\|1\[0-2])-(0\[1-9]\|1\[0-9]\|2\[0-9]\|3\[0-1]} | Optional    |
| shipping.logisticsProvider    | The logistics provider of the shipping                                                                                                                                                                                                                                      | AN255 \[\s\S]{1,255}                                                             | Optional    |
| shipping.trackingNumber       | The tracking number of the shipping                                                                                                                                                                                                                                         | AN255 \[\s\S]{1,255}                                                             | Optional    |
| shipping.returnTrackingNumber | The tracking number issued for returns                                                                                                                                                                                                                                      | AN255 \[\s\S]{1,255}                                                             | Optional    |
| shipping.normalized           | The normalized shipping address.                                                                                                                                                                                                                                            | AN255 \[\s\S]{1,255}                                                             | Optional    |
| shipping.validationStatus     | Indicates whether a address got validated and normalized address got confirmed by the consumer                                                                                                                                                                              | AN255 \[\s\S]{1,255}                                                             | Optional    |
| shipping.warehouse            | The warehouse that fulfilled the order                                                                                                                                                                                                                                      | AN100 \[\s\S]{1,100}                                                             | Optional    |

‌

### Merchant <a href="#merchant" id="merchant"></a>

‌

The merchant data structure holds information about you, the merchant (acceptor). These fields can be used to override the information that is shown on the cardholder statement. It can also be used for payment facilitators.

| Parameter              | Description                                                                                                                                                                                                                                                                                                                  | Format                                                          | Required |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------- |
| merchant.name          | The name of the merchant/acceptor. When used this field will override the value sent as Merchant Name and will normally make up the first line of the card holder statement. Typical usage would be of format `{Merchant DBA Name}*{Description of product or service}`.                                                     | AN100 \[\s\S]{1,100}                                            | Optional |
| merchant.city          | The merchant's city, phone number, email or url. This normally makes up the second line of the card holder statement. It is typical for card present transactions to send the city of the location of transaction and for card not present transactions to send the phone, email or url that the shopper would be recognise. | AN100 \[\s\S]{1,100}                                            | Optional |
| merchant.street        | The door number, floor, building number, building name, and/or street name of the merchant                                                                                                                                                                                                                                   | AN100 \[\s\S]{1,100}                                            | Optional |
| merchant.postcode      | The postal code or zip code of the merchant                                                                                                                                                                                                                                                                                  | AN10 \[A-Za-z0-9\\-]{1,10}                                      | Optional |
| merchant.state         | The county, state or region of the merchant                                                                                                                                                                                                                                                                                  | AN50 \[a-zA-Z0-9]{1,50}                                         | Optional |
| merchant.country       | The country of the merchant                                                                                                                                                                                                                                                                                                  | A2 \[A-Za-z]{2}                                                 | Optional |
| merchant.phone         | The merchants's phone number.                                                                                                                                                                                                                                                                                                | AN25 \[a-zA-Z0-9\\+-.]{0, 25}                                   | Optional |
| merchant.mcc           | The merchants's category code.                                                                                                                                                                                                                                                                                               | AN4 \[a-zA-Z0-9]{0, 4}                                          | Optional |
| merchant.submerchantId | Used only for MasterCard Payment Facilitators. The id of the sub-merchant.                                                                                                                                                                                                                                                   | AN100 \[\s\S]{1,100}                                            | Optional |
| merchant.data\[key]    | The additional data received from merchant alongside with transaction data.                                                                                                                                                                                                                                                  | key: AN64 \[a-zA-Z0-9\\.\_]{3,64} value: AN2048 \[\s\S]{0,2048} | Optional |
| merchant.websiteId     | The website id of merchant, represents random session id unique for current transaction.                                                                                                                                                                                                                                     | AN255 \[\s\S]{0,255}                                            | Optional |

‌

### Cart <a href="#cart" id="cart"></a>

‌

#### Cart items <a href="#cart-items" id="cart-items"></a>

‌

The cart data structure holds product information about the shopping cart such as the product's ID, name, quantity and price. The cart items are counted up by changing the index-number \[n], starting with 0, and maximum 1000. Example: cart.items\[0].name=First Cart Item

| Parameter                             | Description                                                                                                                             | Format                                                              | Required    |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------- |
| cart.items\[n].name                   | The name of the item in the shopping cart. Example: cart.items\[0].name=First Cart Item                                                 | AN255 \[\s\S]{1,255}                                                | Conditional |
| cart.items\[n].merchantItemId         | The unique identifier of the item in the shopping cart.                                                                                 | AN255 \[\s\S]{1,255}                                                | Conditional |
| cart.items\[n].quantity               | The number of items in the shopping cart.                                                                                               | N5 \[0-9]{1,12}(\\\\.\[0-9]{0,3})                                   | Conditional |
| cart.items\[n].type                   | The type of the purchased item in the shopping cart. Values can be: PHYSICAL, DIGITAL, MIXED, ANONYMOUS\_DONATION, AUTHORITIES\_PAYMENT | AN255 \[\s\S]{1,255}                                                | Conditional |
| cart.items\[n].sku                    | The sku cart item.                                                                                                                      | AN255 \[\s\S]{1,255}                                                | Optional    |
| cart.items\[n].currency               | The currency of the price of the shopping cart.                                                                                         | A3 [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code | Conditional |
| cart.items\[n].description            | The description of the item in the shopping cart.                                                                                       | AN2048 \[\s\S]{1,2048}                                              | Conditional |
| cart.items\[n].price                  | The price of the item in the shopping cart. (including tax and discount). The item's price is independent of the quantity.              | N13 \[0-9]{1,10}\\.\[0-9]{2}                                        | Conditional |
| cart.items\[n].totalAmount            | The total amount of the cart item including quantity.                                                                                   | N13 \[0-9]{1,10}\\.\[0-9]{2}                                        | Conditional |
| cart.items\[n].taxAmount              | The tax amount of the cart item. The item's tax amount is independent of the quantity.                                                  | N13 \[0-9]{1,10}\\.\[0-9]{2}                                        | Conditional |
| cart.items\[n].totalTaxAmount         | The total tax amount of the cart item.                                                                                                  | N13 \[0-9]{1,10}\\.\[0-9]{2}                                        | Conditional |
| cart.items\[n].tax                    | The tax percentage applied to the price of the item in the shopping cart.                                                               | AN6 ^(100(\\.00?)?)\|(\[0-9]{1,2}(\\.\[0-9]{1,2})?)$                | Conditional |
| cart.items\[n].shipping               | The shipping amount applied to the item in the shopping cart.                                                                           | N10.N2 \[0-9]{1,10}\\.\[0-9]{2}                                     | Conditional |
| cart.items\[n].discount               | The discount percentage applied to the price of the item in the shopping cart.                                                          | N13 \[0-9]{1,10}\\.\[0-9]{2}                                        | Conditional |
| cart.items\[n].giftMessage            | Gift Message for the specific cart item                                                                                                 | AN255 \[\s\S]{1,255}                                                | Optional    |
| cart.items\[n].shippingMethod         | Shipping method for the cart item.                                                                                                      | AN255 \[\s\S]{1,255}                                                | Optional    |
| cart.items\[n].shippingInstructions   | Shipping instructions for the cart item.                                                                                                | AN255 \[\s\S]{1,255}                                                | Optional    |
| cart.items\[n].shippingTrackingNumber | Shipping tracking number for the cart item                                                                                              | AN255 \[\s\S]{1,255}                                                | Optional    |
| cart.items\[n].originalPrice          | The cart item's price before discounts. The item's price is independent of the quantity.                                                | AN255 \[\s\S]{1,255}                                                | Optional    |
| cart.items\[n].quantityUnit           | The cart item's unit of quanity.                                                                                                        | M, CM, KG, G, COUNT (default)                                       | Optional    |
| cart.items\[n].productUrl             | The cart item's URL.                                                                                                                    | Valid URL                                                           | Optional    |
| cart.items\[n].imageUrl               | The cart item's image URL.                                                                                                              | Valid URL                                                           | Optional    |
| cart.items\[n].totalDiscountAmount    | The cart item's total discount amount. The total discount amount is related to the discount percentage                                  | N10.N2\[0-9]{1,10}\\.\[0-9]{2}                                      | Optional    |

‌

#### Cart payments <a href="#cart-payments" id="cart-payments"></a>

‌

The cart payments data structure holds information about already made payments associated with the cart. The cart payments are counted up by changing the index-number \[n], starting with 0. Example: cart.payments\[0].name=First Cart Item

| Parameter                  | Description                                                                                                                                                  | Format                          | Required |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | -------- |
| cart.payments\[n].name     | The name of the payment methtod. Example: cart.payments\[0].name=promotion giftcard 50                                                                       | AN255 \[\s\S]{1,255}            | Optional |
| cart.payments\[n].type     | The type of the used payment. One of the options: GIFTCARD, PROMOTION Example: cart.payments\[0].type=GIFTCARD                                               | AN255 \[\s\S]{1,255}            | Optional |
| cart.payments\[n].amount   | The amount of the associated and already used payment method. Example: cart.payments\[0].amount=10.90                                                        | N10.N2 \[0-9]{1,10}\\.\[0-9]{2} | Optional |
| cart.payments\[n].currency | The currency of the already used payment amount. Example: cart.payments\[0].currency=EUR                                                                     | A3 \[a-zA-Z]{3}                 | Optional |
| cart.payments\[n].status   | The status of the already used payment method. One of the options: pending, authorized, captured Example: cart.payments\[0].status=captured                  | AN255 \[\s\S]{1,255}            | Optional |
| cart.payments\[n].brand    | The brand of the already used payment method, eg. SVS Example: cart.payments\[0].name=SVS                                                                    | AN255 \[\s\S]{1,255}            | Optional |
| cart.payments\[n].primary  | Identifies this payment method being the primary payment method used for that cart. One of the options: true, false Example: cart.payments\[0].primary=false | true\|false                     | Optional |

‌

### Airline <a href="#airline" id="airline"></a>

‌

The airline data structure holds passenger and trip leg airline information. The airline passenger and leg items are counted up by changing the index-number \[n], starting with 0. Example: airline.passengers\[0].name=Jane Jones

| Parameter                                          | Description                                          | Format                                                                           | Required    |
| -------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------- | ----------- |
| airline.totalTaxAmount                             | The total amount of tax                              | N10.N2 \[0-9]{1,10}\\.\[0-9]{2}                                                  | Conditional |
| airline.totalFeesAmount                            | The total fees                                       | N10.N2 \[0-9]{1,10}\\.\[0-9]{2}                                                  | Conditional |
| airline.totalFareAmount                            | The total fare                                       | N10.N2 \[0-9]{1,10}\\.\[0-9]{2}                                                  | Conditional |
| airline.ticketIssueDate                            | The date the booking/ticket was made                 | AN10 {19\|20)(\[0-9]{2})-(0\[1-9]\|1\[0-2])-(0\[1-9]\|1\[0-9]\|2\[0-9]\|3\[0-1]} | Conditional |
| airline.ticketIssueAddress                         | The address that issued the ticket                   | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.thirdPartyBooking                          | Indicates if the ticket was booked via a third party | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.bookingtype                                | The type of booking                                  | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.ticketDeliveryMethod                       | The delivery method of the ticket                    | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.bookingRefNum                              | The booking reference number                         | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.agentName                                  | The agent name                                       | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.agentCode                                  | The agent code                                       | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].type                        | The passenger type                                   | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].name                        | The name of the passenger                            | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].ticketRestricted            | Indicates if the passenger has a restricted ticket   | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].ticketNumber                | The passenger's ticket number                        | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].status                      | The passenger status                                 | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].phone                       | The passenger's phone                                | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].frequentFlyerNumber         | The passenger's frequent flyer number                | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].email                       | The passenger's email                                | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].dob                         | The passenger's date of birth                        | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].checkDigit                  | The check digit for the passenger                    | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].ticketNumber       | The ticket number for the leg                        | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].taxAmount          | The tax amount for the leg                           | N10.N2 \[0-9]{1,10}\\.\[0-9]{2}                                                  | Conditional |
| airline.passengers\[n].legs\[n].stopOverAllowed    | Indicates if a stop over is allowed                  | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].restrictions       | Indicates if there is restrictions for the leg       | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].flightNumber       | The flight number for the leg                        | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].feesAmount         | The fees for the leg                                 | N10.N2 \[0-9]{1,10}\\.\[0-9]{2}                                                  | Conditional |
| airline.passengers\[n].legs\[n].fareBasis          | The fare basis for the leg                           | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].fareAmount         | The fare amount for the leg                          | N10.N2 \[0-9]{1,10}\\.\[0-9]{2}                                                  | Conditional |
| airline.passengers\[n].legs\[n].exchangeTicketNum  | The exchange ticket number for the leg               | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].departureTaxAmount | The departure tax amount for the leg                 | N10.N2 \[0-9]{1,10}\\.\[0-9]{2}                                                  | Conditional |
| airline.passengers\[n].legs\[n].departureCountry   | The departure country for the passenger              | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].departureAirport   | The departure airport for the passenger              | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].airlineName        | The name of the airline for the leg                  | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].airlineCode        | The code of the airline for the leg                  | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].departureTime      | The departure time for the leg                       | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].departureDate      | The departure date for the leg                       | AN10 {19\|20)(\[0-9]{2})-(0\[1-9]\|1\[0-2])-(0\[1-9]\|1\[0-9]\|2\[0-9]\|3\[0-1]} | Conditional |
| airline.passengers\[n].legs\[n].arrivalCountry     | The destination country for the leg                  | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].arrivalAirport     | The destination airport for the leg                  | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].arrivalTime        | The arrival time for the leg                         | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].arrivalDate        | The arrival date for the leg                         | AN10 {19\|20)(\[0-9]{2})-(0\[1-9]\|1\[0-2])-(0\[1-9]\|1\[0-9]\|2\[0-9]\|3\[0-1]} | Conditional |
| airline.passengers\[n].legs\[n].couponNumber       | The coupon number for the leg                        | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].classOfService     | The class of service for the leg                     | AN255 \[\s\S]{1,255}                                                             | Conditional |
| airline.passengers\[n].legs\[n].carrierCode        | The carrier code for the leg                         | AN255 \[\s\S]{1,255}                                                             | Conditional |

‌

### Tokenization and Registration <a href="#tokenization-and-registration" id="tokenization-and-registration"></a>

‌

As described in the [Tokenization Guide](https://primeiropay.docs.oppwa.com/tutorials/server-to-server/tokenisation) there are two ways to store a customer's data on the system. Either directly POST to the registration endpoint or add the following parameter to a payment:

| Parameter          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Format         | Required |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | -------- |
| createRegistration | If true, the payment details will be stored with the request. As part of the response, you will receive the parameter registration.id which you can use to reference the registration for later payments.                                                                                                                                                                                                                                                                                                                                                                                 | A5 true\|false | Optional |
| overrideHolder     | If true, it allows to send in the card.holder or bankAccount.holder to override the empty holder from the registration/tokenization transaction. It applies only to that particular payment and does not change the holder value of the registration transaction. For one-click payment, the edit box appears as the replacement over the empty label to allow the user to input the new value for the holder. This parameter is available on prepare (and update) checkout step of PrimeiroPay as well as when sending the payment over registration one-click payment Server-to-Server. | A5 true\|false | Optional |

‌

### Recurring <a href="#recurring" id="recurring"></a>

‌

As described in the [Recurring Payments Guide](https://developers.primeiropay.com/getting-started/server-to-server-api/recurring-1), all you have to do for sending recurring transactions is to flag the transaction with the following parameter:

| Parameter                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Format                | Required |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | -------- |
| recurringType                  | <p>Used to indicate the type of recurring payment.</p><ul><li><strong>INITIAL</strong>: The payment is the first of a series of payments. This first payment has to contain additional data like the CVV code or 3D parameters to enable an initial authentication of the request.</li><li><strong>REPEATED</strong>: The payment is a subsequent payment. It may not contain shopper authentication data like the CVV code or 3D parameters - the shopper is not present anymore.</li></ul> | A20 INITIAL\|REPEATED | Optional |
| recurring.numberOfInstallments | The number of installments the payment should be split into.                                                                                                                                                                                                                                                                                                                                                                                                                                 | N3                    | Optional |

‌

### Recurring Migration <a href="#recurring-migration" id="recurring-migration"></a>

‌

To do a migration of recurring payment you need to do a registration (RG) with INITIAL transaction data that are send with the following parameters:

| Parameter                           | Description                                                                             | Format                                                                                                                       | Required    |
| ----------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------- |
| recurringMigration.paymentType      | Indicates the payment type of the INITIAL request(DB\|CD\|PA).                          | A2                                                                                                                           | Mandatory   |
| recurringMigration.amount           | Indicates the INITIAL payment amount.                                                   | N8.N2 \[0-9]{1,8}(\\.\[0-9]{2})?                                                                                             | Optional    |
| recurringMigration.requestTimestamp | Indicates the timestamp of the INITIAL payment request (e.g. 2018-11-27 10:42:39+0000). | AN19 (19\|20)(\[0-9]{2})-(0\[1-9]\|1\[0-2])-(0\[1-9]\|1\[0-9]\|2\[0-9]\|3\[0-1] 0\[0-2]1\[0-9]:0\[0-5]1\[0-9]:0\[0-5]1\[0-9] | Conditional |
| recurringMigration.connectorTxId1   | Indicates INITIAL payment response details as received from the acquirer.               | AN128 \[\s\S]{1,128}                                                                                                         | Conditional |
| recurringMigration.connectorTxId2   | Indicates INITIAL payment response details as received from the acquirer.               | AN128 \[\s\S]{1,128}                                                                                                         | Conditional |
| recurringMigration.connectorTxId3   | Indicates INITIAL payment response details as received from the acquirer.               | AN128 \[\s\S]{1,128}                                                                                                         | Conditional |

‌

### 3D Secure <a href="#id-3d-secure" id="id-3d-secure"></a>

‌

The 3D secure data structure is used to hold authentication data generated by the 3D secure MPI when an external MPI is being used, or additional information about the authentication. If 3D data is present which indicates the usage of an external MPI (xid, eci, verificationId), the payment gateway will just pass through these values to the acquiring system. For more detailed information about the required fields for 3D Secure version 2.0 and above, please visit the 3D Secure 2.0 guide [here](https://primeiropay.docs.oppwa.com/support/3d-secure-2.0-guide)​

| Parameter                                   | Description                                                                                                                                                                                                  | Format                   | Required    |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | ----------- |
| threeDSecure.eci                            | The ECI for the 3D secure request. Required when using a third-party MPI Example: threeDSecure.eci=01                                                                                                        | N2 0\[1-8]{1}            | Conditional |
| threeDSecure.verificationId                 | The 3D secure CAVV or AAV. Required when using a third-party MPI. Must be Base64 encoded.                                                                                                                    | AN28 \[\s\S]{28}         | Conditional |
| threeDSecure.xid                            | The 3D secure xid if available. Must be Base64 encoded.                                                                                                                                                      | AN64 \[\s\S]{64}         | Conditional |
| threeDSecure.enrollmentStatus               | The enrollment status for the 3D secure request. Required when using a third-party MPI.                                                                                                                      | AN1 \[YUN]               | Conditional |
| threeDSecure.authenticationStatus           | The authentication status for the 3D secure request. Required when using a third-party MPI.                                                                                                                  | AN1 \[YAUN]              | Conditional |
| threeDSecure.merchant.name                  | Merchant name as defined by the Scheme Directory Server.                                                                                                                                                     | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.merchant.url                   | Merchant URL                                                                                                                                                                                                 | AN2048 \[\s\S]{0,2048}   | Optional    |
| threeDSecure.merchant.country               | Merchant country                                                                                                                                                                                             | AN3 A3 \[A-Za-z]{3}      | Optional    |
| threeDSecure.v1.visa.requestorId            | Merchant ID for 3D Secure version 1.0, assigned by Visa.                                                                                                                                                     | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v1.mastercard.requestorId      | Merchant ID for 3D Secure version 1.0, assigned by Mastercard.                                                                                                                                               | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v1.diners.requestorId          | Merchant ID for 3D Secure version 1.0, assigned by Diners/Discover.                                                                                                                                          | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v1.diners.password             | Password for the Diners/Discover ProtectBuy Directory Server. Used for 3D Secure 1.0                                                                                                                         | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v1.amex.requestorId            | Merchant ID for 3D Secure version 1.0, assigned by American Express.                                                                                                                                         | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v1.jcb.requestorId             | Merchant ID for 3D Secure version 1.0, assigned by JCB.                                                                                                                                                      | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v1.jcb.password                | Password for the JCB J/Secure Directory Server. Used for 3D Secure 1.0                                                                                                                                       | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v1.dankort.requestorId         | Merchant ID for 3D Secure version 1.0, assigned by Dankort.                                                                                                                                                  | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v1.bcmc.requestorId            | Merchant ID for 3D Secure version 1.0, assigned by Bancontact/Mistercash.                                                                                                                                    | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.visa.requestorId            | Requestor ID for 3D Secure version 2, assigned by Visa.                                                                                                                                                      | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.visa.requestorName          | Requestor Name for 3D Secure version 2, assigned by Visa.                                                                                                                                                    | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.mastercard.requestorId      | Requestor ID for 3D Secure version 2, assigned by Mastercard.                                                                                                                                                | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.mastercard.requestorName    | Requestor Name for 3D Secure version 2, assigned by Mastercard.                                                                                                                                              | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.amex.requestorId            | Requestor ID for 3D Secure version 2, assigned by American Express.                                                                                                                                          | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.amex.requestorName          | Requestor Name for 3D Secure version 2, assigned by American Express.                                                                                                                                        | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.diners.requestorId          | Requestor ID for 3D Secure version 2, assigned by Diners/Discover.                                                                                                                                           | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.diners.requestorName        | Requestor Name for 3D Secure version 2, assigned by Diners/Discover.                                                                                                                                         | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.jcb.requestorId             | Requestor ID for 3D Secure version 2, assigned by JCB.                                                                                                                                                       | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.jcb.requestorName           | Requestor Name for 3D Secure version 2, assigned by JCB.                                                                                                                                                     | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.cartebancaire.requestorId   | Requestor ID for 3D Secure version 2, assigned by Carte Bancaire.                                                                                                                                            | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.v2.cartebancaire.requestorName | Requestor Name for 3D Secure version 2, assigned by Carte Bancaire.                                                                                                                                          | AN100 \[\s\S]{100}       | Optional    |
| threeDSecure.dsTransactionId                | Transaction ID assigned by the directory server. Used when the transaction was already authenticated via 3D Secure version 2, using an external MPI.                                                         | AN100 \[\s\S]{36}        | Optional    |
| threeDSecure.version                        | Version of the 3D Secure that was used when the transaction was already authenticated using an external MPI. For example: 1.0.2 or 2.1.0                                                                     | (1\|2)\\.\[0-9]\\.\[0-9] | Optional    |
| threeDSecure.challengeIndicator             | Indicates whether a challenge is requested for this transaction. Can be sent when 3D Secure version 2.2 or higher is used.                                                                                   | 0\[1-9]                  | Optional    |
| threeDSecure.challengeMandatedIndicator     | Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variable. Can be used when the transaction was authenticated via an external MPI. | AN1 (Y\|N)               | Optional    |
| threeDSecure.authType                       | The type of authentication that was requested by the ACS. Can be used when the transaction was authenticated via an external MPI.                                                                            | AN2 0\[1-4]              | Optional    |
| threeDSecure.exemptionFlag                  | Flags the transaction as exemption during authorization. Can be used for 3D Secure version 2.2 or higher.                                                                                                    | N2 0\[1-4]               | Optional    |
| threeDSecure.transactionStatusReason        | Provides information on why the Transaction Status field has the specified value. Can be used when the transaction was authenticated via an external MPI.                                                    | N2                       | Optional    |

‌

### Custom Parameters <a href="#custom-parameters" id="custom-parameters"></a>

‌

Custom parameters are unspecified fields that can be used to send custom data. The data sent in these fields are echoed back in the response.

| Parameter               | Description                                                                                                                                                                                                                      | Format                                                           | Required    |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------- |
| customParameters\[name] | A name value pair used for sending custom information. NOTE: customParameters that are sent from the client-side (e.g. for PrimeiroPay) should be prepended with SHOPPER\_\*, for example customParameters\[SHOPPER\_customerId] | name: AN64 \[a-zA-Z0-9\\.\_]{3,64} value: AN2048 \[\s\S]{0,2048} | Conditional |

‌

### Asynchronous payments <a href="#asynchronous-payments" id="asynchronous-payments"></a>

‌

Asynchronous payment methods like 3D secure, online transfer or virtual wallets have additional steps in their workflow. The response to your initial payment request will be pending and contain a redirect URL to the receiver system that the shopper should be forwarded to.

| Parameter        | Description                                                                                     | Format                 | Required    |
| ---------------- | ----------------------------------------------------------------------------------------------- | ---------------------- | ----------- |
| shopperResultUrl | This URL will receive the result of an asynchronous payment. Must be sent URL encoded.          | AN2048 \[\s\S]{6,2048} | Conditional |
| notificationUrl  | This URL will receive the asynchronous notification where applicable. Must be sent URL encoded. | AN2048 \[\s\S]{6,2048} | Optional    |

‌

The response parameters:

| Parameter                     | Description                                                                                                                                                       | Format                 | Required    |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----------- |
| redirect.url                  | URL the the shopper must be redirected to in order to proceed.                                                                                                    | AN2048 \[\s\S]{6,2048} | Conditional |
| redirect.parameters\[n].name  | List of parameter names for the redirect.url. The corresponding parameter value is the same parameter number ending with .value like described in the line below. | AN255 \[\s\S]{1,255}   | Conditional |
| redirect.parameters\[n].value | The parameter values corresponding to the names as described above.                                                                                               | AN255 \[\s\S]{1,255}   | Conditional |

‌

### Webhook Notifications <a href="#webhook-notifications" id="webhook-notifications"></a>

‌

When you register a webhook, you'll receive notifications on the registered Url. These notifications are basically standard responses (wrapped in the "payload") of different types.

| Parameter | Description                                                                                                                                                                                                                                                                                                            | Format                      | Required    |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ----------- |
| type      | <p>Type of notification</p><ul><li><strong>PAYMENT</strong> This type of notification is sent when payment is created or updated in the system.</li><li><strong>REGISTRATION</strong> This type of notification is sent when we get new registration request, or the existing registration has been deleted.</li></ul> | (PAYMENT\|REGISTRATION)     | Required    |
| action    | <p>Indicator of status change</p><ul><li><strong>CREATED</strong> e.g., When registration has been created.</li><li><strong>UPDATED</strong> e.g., When registration has been updated.</li><li><strong>DELETED</strong> e.g., When registration has been deleted.</li></ul>                                            | (CREATED\|UPDATED\|DELETED) | Conditional |
| payload   | Content of notification. If the notification type is payment or registration, payload will be identical to payment response you received.                                                                                                                                                                              | JSON                        | Required    |

‌

In addition to standard response parameters, these notifications specific are available:

| Parameter            | Description                               | Format                          | Required    |
| -------------------- | ----------------------------------------- | ------------------------------- | ----------- |
| presentationAmount   | The presentation amount of the request.   | N10.N2 \[0-9]{1,10}\\.\[0-9]{2} | Conditional |
| presentationCurrency | The presentation currency of the request. | A3 \[a-zA-Z]{3}                 | Conditional |

‌

### Reporting <a href="#reporting" id="reporting"></a>

‌

The following parameters are used when calling the reporting endpoints.

| Parameter | Description                                      | Format                                                                           | Required |
| --------- | ------------------------------------------------ | -------------------------------------------------------------------------------- | -------- |
| date.from | The date from which the report data should start | AN10 {19\|20)(\[0-9]{2})-(0\[1-9]\|1\[0-2])-(0\[1-9]\|1\[0-9]\|2\[0-9]\|3\[0-1]} | Required |
| date.to   | The date on which the report data should end     | AN10 {19\|20)(\[0-9]{2})-(0\[1-9]\|1\[0-2])-(0\[1-9]\|1\[0-9]\|2\[0-9]\|3\[0-1]} | Required |

‌

### Giftcard <a href="#giftcard" id="giftcard"></a>

‌

A giftcard allows you to send additional information for payments and risk checks that have a gift card.

| Parameter        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Format               | Required |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------- |
| giftCard.message | Message that should be written on the gift card.                                                                                                                                                                                                                                                                                                                                                                                                              | AN160 \[\s\S]{2,160} | Optional |
| giftCard.type    | Type of the Gift Card. One of the options: ANNIVERSARY, BIRTHDAY, CONGRATULATIONS, APRIL\_FOOLS\_DAY, EASTER, FATHERS\_DAY, GRADUATION, HOLIDAY, SEASONS\_GREETINGS, PASSOVER, KWANZAA, HALLOWEEN, MOTHERS\_DAY, NEW\_YEARS\_DAY, BOSSES\_DAY, ST\_PATRICKS\_DAY, SWEETEST\_DAY, CHRISTMAS, BABY\_SHOWER, THANKSGIVING, OTHER, VALENTINES\_DAY, WEDDING, SECRETARYS\_DAY, CHINESE\_NEW\_YEAR, HANUKKAH, CELEBRATE\_FALL, GRANDPARENTS\_DAY, INDEPENDENCE\_DAY | AN16                 | Optional |

‌

### Risk <a href="#risk" id="risk"></a>

‌

The following parameters are additional parameters available for risk checks e.g. using the ReD Shield.

| Parameter              | Description                                                                                                                                                                                                                                                                                           | Format                                                                                                                          | Required |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- |
| risk.channelId         | Id of the channel in the risk system. This field is usually set up as a configuration, but in some situations you might want to use the dynamic request based option described here. For the ReD Shield this will cause a different set of rules to be executed. There the length is limited to AN12. | AN255 \[\s\S]{1,255}                                                                                                            | Optional |
| risk.serviceId         | Id of the service in the risk system. This field is usually set up as a configuration, but in some situations you might want to use the dynamic request based option described here. For the ReD Shield this defines which fraud screening service to use. There the length is limited to AN1.        | AN255 \[\s\S]{1,255}                                                                                                            | Optional |
| risk.amount            | Amount for the risk request. The dot is used as decimal separator. Currently this parameter is used for both ReD Shield and 3D Secure. When performing the 3D Secure, if this parameter is present, its value will be used as the amount for the 3D Secure.                                           | N10.N2 \[0-9]{1,10}\\.\[0-9]{2}                                                                                                 | Optional |
| risk.orderTimestamp    | Timestamp of the order for the risk request. Format: yyyy-MM-dd hh:mm:ss (24h clock), e.g. 2015-12-17 22:00:04 By default our payment system sets a timestamp automatically. Use this field when the (payment) transaction was executed at a different time than sending the risk request at hand.    | AN19 {(19\|20)(\[0-9]{2})-(0\[1-9]\|1\[0-2])-(0\[1-9]\|1\[0-9]\|2\[0-9]\|3\[0-1] 0\[0-2]1\[0-9]:0\[0-5]1\[0-9]:0\[0-5]1\[0-9] } | Optional |
| risk.brand             | Brand of the payment that is being checked. By default you can use the field paymentBrand instead of this one. However, if the payment isn't executed through the OPP you might have a different brand-format you can specify here.                                                                   | AN255 \[\s\S]{1,255}                                                                                                            | Optional |
| risk.parameters\[name] | A name value pair used for sending custom information related to the risk request.                                                                                                                                                                                                                    | name: AN64 \[a-zA-Z0-9\\.\_]{3,64} value: AN2048 \[\s\S]{0,2048}                                                                | Optional |
| risk.merchantWebsite   | Merchant's website URL                                                                                                                                                                                                                                                                                | AN60 \[\s\S]{1,60}                                                                                                              | Optional |
| risk.accountToken      | A merchant-set token for the account                                                                                                                                                                                                                                                                  | AN64 \[\s\S]{1,64}                                                                                                              | Optional |

‌

### Scheduling Payment Jobs <a href="#scheduling-payment-jobs" id="scheduling-payment-jobs"></a>

‌

The following parameters are additional parameters available for scheduling payment jobs

| Parameter          | Description                                                                                                                                                                                                                            | Format                                                                                    | Required |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------- |
| job.name           | The name of the job to be scheduled                                                                                                                                                                                                    | AN64 \[\s\S]{1,64}                                                                        | Optional |
| job.year           | Here you can specify/limit which year(s) the job will run You can specify specific year, or comma separated years or \* which means endless.                                                                                           | (\d{4})?(\\,\d{4})\*\|\\\*                                                                | Optional |
| job.month          | Here you can specify/limit which year(s) the job will run You can specify specific month, or comma separated months or \* which means endless.                                                                                         | (\d{2})?(\\,\d{2})\*\|\\\*                                                                | Optional |
| job.dayOfMonth     | Here you can specify/limit which day(s) the job will run You can specify specific day, or comma separated days or \* which means endless. Note that you can't specify both dayOfMonth and dayOfWeek, only one should be specified      | (\d{2})?(\\,\d{2})\*\|\\\*                                                                | Optional |
| job.dayOfWeek      | Here you can specify/limit which week day(s) the job will run You can specify specific day, or comma separated days or \* which means endless. Note that you can't specify both dayOfMonth and dayOfWeek, only one should be specified | (\d)?(\\,\d)\*\|\\\*                                                                      | Optional |
| job.hour           | Here you can specify/limit which week hour(s) the job will run You can specify specific hour, or comma separated hours or \* which means endless.                                                                                      | (\d{2})?(\\,\d{2})\*\|\\\*                                                                | Optional |
| job.minute         | Here you can specify/limit which week minute(s) the job will run You can specify specific minute, or comma separated minutes or \* which means endless.                                                                                | (\d{2})?(\\,\d{2})\*\|\\\*                                                                | Optional |
| job.second         | Here you can specify/limit which week second(s) the job will run You can specify specific second, or comma separated minutes or \* which means endless.                                                                                | (\d{2})?(\\,\d{2})\*\|\\\*                                                                | Optional |
| job.startDate      | Here you can specify starting at which date/time this job should be executed                                                                                                                                                           | yyyy-MM-dd HH:mm:ss                                                                       | Optional |
| job.endDate        | Here you can specify at which date/time this job should be ended                                                                                                                                                                       | yyyy-MM-dd HH:mm:ss                                                                       | Optional |
| job.noticeUnit     | Here you can specify the date/time unit of noticeNumber                                                                                                                                                                                | "YEAR"\|"MONTH"\|"WEEK"\|"DAY"\|"HOUR"\|"MINUTE"\|"SECOND"                                | Optional |
| job.noticeNumber   | The notice to deschedule the job before until duration end                                                                                                                                                                             | Number                                                                                    | Optional |
| job.noticeCallable | When the notice could be callable?                                                                                                                                                                                                     | ANYTIME\|DURATION\_END                                                                    | Optional |
| job.durationUnit   | Here you can specify the date/time unit of durationNumber                                                                                                                                                                              | "YEAR"\|"MONTH"\|"WEEK"\|"DAY"\|"HOUR"\|"MINUTE"\|"SECOND"                                | Optional |
| job.durationNumber | The minimum time/date of the duration of the job                                                                                                                                                                                       | Number                                                                                    | Optional |
| job.expression     | You can specify a cron expression here that represents how often the job will run If you specify this parameter, then it will overrite (year,month,dayOfMonth,dayOfWeek,hour, minute and second) parameters values                     | See <http://www.quartz-scheduler.org/documentation/quartz-2.x/tutorials/crontrigger.html> | Optional |

‌

### Payment Response Parameters <a href="#payment-response-parameters" id="payment-response-parameters"></a>

| Parameter                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Format                                                           | Required    |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------- |
| id (/checkouts)                | The identifier of the checkout request that can be used to reference the payment later. You get this as the field `id` of a checkout's response and then should use it as the {id} part in step 2 and step 3 of the [integration guide](https://primeiropay.docs.oppwa.com/tutorials/integration-guide).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | AN48 \[a-zA-Z0-9.\\-]{32,48}                                     | required    |
| id (/payments)                 | The identifier of the payment request that can be used to reference the payment later. You get this as the field `id` of a payment's response and then can use it as `referencedPaymentId` in the [backoffice tutorial](https://primeiropay.docs.oppwa.com/tutorials/manage-payments/backoffice) or as the {id} part of the URL for sending referencing requests.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | AN32 \[a-zA-Z0-9]{32}                                            | required    |
| id (/registrations)            | The identifier of the registration request that can be used to reference the registration later. You get this either as the field `id` of a registration's response or as the field `registrationId` of a payment's response (if the request contained [createRegistration=true](https://primeiropay.docs.oppwa.com/tutorials/server-to-server/tokenisation)). You should use it for requests referencing this registration as the {id} part of the URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | AN32 \[a-zA-Z0-9]{32}                                            | required    |
| referencedId                   | In case of referenced payment (e.g., Capture or Refund), this fields included to see which payment was referenced. **Note:** This fields is only for webhook notification.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | AN32 \[a-zA-Z0-9]{32}                                            | Conditional |
| paymentBrand                   | The payment brand of the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | AN32 \[a-zA-Z0-9\_] {1,32}                                       | Conditional |
| amount                         | The amount of the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | N10.N2 \[0-9]{1,10}\\.\[0-9]{2}                                  | Conditional |
| currency                       | The currency of the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | A3 \[a-zA-Z]{3}                                                  | Conditional |
| descriptor                     | The descriptor of the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | AN127 \[\s\S]{1,127}                                             | Conditional |
| result.code                    | The unique code that indicates the result status of the request. See the [result codes](https://primeiropay.docs.oppwa.com/reference/resultCodes) for more detailed information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | AN11 \[0-9\\.]{2,11}                                             | Required    |
| result.description             | A textual description explaining the result.code's meaning.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | AN255 \[\s\S]{0,255}                                             | Optional    |
| result.avsResponse             | Contains the AVS response returned by the acquirer. It may include one the following result: A = Address does match, zip code does not match Z = Address does not match, zip code does match N = Address and zip code do not match U = Technical or logical error. AVS cannot be applied on card or address (not UK or US issuer), issuer is not available, etc. F = Address and Postal Code Matches                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | A1 \[A-Z]{1}                                                     | Conditional |
| result.cvvResponse             | <p>Contains the CVV response returned by the acquirer. It may include one the following result:</p><ul><li><strong>M - CVV2 Match</strong> Indicates that the issuer was able to verify the CVV2 value provided by the merchant.</li><li><strong>N - CVV2, CVC2, Discover CID or AMEX CID do not match</strong> Indicates that the issuer was not able to verify the CVV2 value provided by the merchant.</li><li><strong>P - Not Processed</strong> Indicates that the issuer was unable to verify the CVV2 value provided by the merchant because either their verification system was not functioning, or not all of the information needed to verify the CVV2 value (such as the expiration date) was included in the request.</li><li><strong>S - CVV2, CVC2, Discover CID or AMEX CID data is not present on the card, but the issuer indicated it should be present</strong> Indicates that the issuer was unable to perform CVV2 verification, and notifies the merchant that the card should contain a CVV2 value.</li><li><strong>U - Unsupported by issuer or issuer is unable to process request</strong> Indicates that the issuer is not participating in the CVV2 service, or that the issue has not provided the card Brand with the required encryption keys needed to perform verification, or that STIP has responded with unavailable response.</li></ul> | A1 \[A-Z]{1}                                                     | Conditional |
| resultDetails                  | A container for name value pair used for enriching the response with bank-specific response details. I.e. the actual parameters used within resultDetails are bank-specific. Example: resultDetails.AuthCode=123456                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | name: AN64 \[a-zA-Z0-9\\.\_]{3,64} value: AN2048 \[\s\S]{0,2048} | Optional    |
| resultDetails.AcquirerResponse | Represents the acquirer original response code retrieved from the acquirer directly.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | AN2048 \[\s\S]{0,2048}                                           | Conditional |
| card.bin                       | The first six digits of the card.number                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | N6 \[\d]{6}                                                      | Optional    |
| card.holder                    | Holder of the credit card account                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | N6 \[\d]{6}                                                      | Optional    |
| card.expiryMonth               | The expiry month of the card                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | N6 \[\d]{2}                                                      | Optional    |
| card.expiryYear                | The expiry year of the card                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | N4 \[\d]{4}                                                      | Optional    |
| merchant.bankAccount.holder    | Holder of the merchant's bank account                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | AN128 {4,128}                                                    | Required    |
| merchant.bankAccount.number    | The account number of the merchant's bank account. (IBAN for SEPA accounts)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | AN64 \[a-zA-Z0-9]{3,64}                                          | Conditional |
| merchant.bankAccount.bic       | The BIC (Bank Identifier Code (SWIFT)) number of the merchant's bank account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | AN11 \[a-zA-Z0-9]{8}\|\[a-zA-Z0-9]{11}                           | Conditional |
| merchant.bankAccount.country   | The country code of the merchant's bank account ([ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1)).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | AN2 \[a-zA-Z]{2}                                                 | Conditional |
| risk.score                     | Returns the score of the executed transaction risk checks. The value is a number from -99999 to +99999. Can be returned both for standalone risk requests and payment requests that include risk checks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | AN6 \[-+]?\[0-9]{5}                                              | Conditional |
| Other                          | The response can also contain each of the data structures listed above, such as `customer` and `billingAddress`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | n/a                                                              | Conditional |
| buildNumber                    | Useful for support purposes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | AN255 \[\s\S]{0,255}                                             | Required    |
| timestamp                      | The timestamp the response has generated.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | date yyyy-MM-dd hh:mm:ssZ                                        | Required    |
| ndc                            | An internal unique identifier for the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | AN69 \[a-zA-Z0-9\\-]{1,69}                                       | Required    |

‌

### Reconciliation Response Parameters <a href="#reconciliation-response-parameters" id="reconciliation-response-parameters"></a>

‌

Reconciliation reporting data is available via CSV file from FTP. The structure of the reconciliation reporting csv file is as of following:‌

ReconciliationType;PaymentType;Cashflow;ClearingInstituteMerchantId;MerchantAccountId;MerchantAccountName;PspId;DivisionId;MerchantId;SettlementTxId;UniqueID;ShortId;ConnectorTxId1;ConnectorTxId2;ConnectorTxId3;Amount;Currency;Brand;TxRequestTime;SettlementAmount;SettlementCurrency;SettlementFee;SettlementFxRate;SettlementDate;SettlementStatus;Descriptor;AccountNumberLast4;BankCode;AccountHolder;ReasonCode;ReasonDesc;SettlementFileFormat;ClearingInsitituteName;MatchingStatus;MatchedTransactions;ChargebackId

| Parameter CSV               | Parameter API                      | Description                                                                                                                                                                                                                                                                                                                                                              | Format                                                                                                                      | Required    |
| --------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------- |
| ReasonCode                  | result.code                        | Failure Status Code (available only for Chargebacks)                                                                                                                                                                                                                                                                                                                     | AN11 \[0-9\\.]{2,11}                                                                                                        | optional    |
| ReasonDesc                  | result.description                 | Failure Status Description (available only for Chargebacks)                                                                                                                                                                                                                                                                                                              | AN128                                                                                                                       | optional    |
| SettlementTxId              | settlement.id                      | Transaction ID at Settlement Provider                                                                                                                                                                                                                                                                                                                                    | AN64 \[\s\S]{0,64}                                                                                                          | optional    |
| Cashflow                    | settlement.cashflow                | Transaction Balance Direction                                                                                                                                                                                                                                                                                                                                            | POS, NEG                                                                                                                    | required    |
| SettlementAmount            | settlement.amount                  | Settled Amount                                                                                                                                                                                                                                                                                                                                                           | N13 \[0-9]{1,10}\\.\[0-9]{2}                                                                                                | required    |
| SettlementCurrency          | settlement.currency                | Settlement Currency                                                                                                                                                                                                                                                                                                                                                      | A3 (according to ISO 4217)                                                                                                  | required    |
| SettlementFee               | settlement.fee                     | Settlement Fee                                                                                                                                                                                                                                                                                                                                                           | N13 \[0-9]{1,10}\\.\[0-9]{2}                                                                                                | optional    |
| SettlementFxRate            | settlement.fxRate                  | Settlement FX Rate                                                                                                                                                                                                                                                                                                                                                       | N13 \[0-9]{1,10}\\.\[0-9]{2}                                                                                                | required    |
| SettlementDate              | settlement.date                    | Date on which settlement is executed by the Clearing Institute in its time zone                                                                                                                                                                                                                                                                                          | ​Content                                                                                                                    | required    |
| SettlementStatus            | settlement.status                  | Settlement Status                                                                                                                                                                                                                                                                                                                                                        | SUCCESS, FAILED                                                                                                             | required    |
| SettlementFileFormat        | settlement.format                  | File format of Settlement File                                                                                                                                                                                                                                                                                                                                           | AN32                                                                                                                        | required    |
| ClearingInsitituteName      | clearingInstitute.name             | Name of Clearing Institute                                                                                                                                                                                                                                                                                                                                               | AN64                                                                                                                        | required    |
| ClearingInstituteMerchantId | clearingInstitute.merchantId       | Merchant ID at Settlement Provider                                                                                                                                                                                                                                                                                                                                       | AN64 \[\s\S]{5..64}                                                                                                         | required    |
| ConnectorTxId1              | clearingInstitute.txId1            | Additional field for a transaction related reference (provided by the Clearing Institute)                                                                                                                                                                                                                                                                                | AN64                                                                                                                        | optional    |
| ConnectorTxId2              | clearingInstitute.txId2            | Additional field for a transaction related reference (provided by the Clearing Institute)                                                                                                                                                                                                                                                                                | AN64                                                                                                                        | optional    |
| ConnectorTxId3              | clearingInstitute.txId3            | Additional field for a transaction related reference (provided by the Clearing Institute)                                                                                                                                                                                                                                                                                | AN64                                                                                                                        | optional    |
| AccountNumberLast4          | card.last4Digits                   | Last 4 digits of the credit/debit card                                                                                                                                                                                                                                                                                                                                   | AN4                                                                                                                         | optional    |
| AccountHolder               | card.holder                        | Account Holder of credit/debit card acount                                                                                                                                                                                                                                                                                                                               | AN128                                                                                                                       | optional    |
| AccountNumberLast4          | bankAccount.last4Digits            | Last 4 digits of the bank account                                                                                                                                                                                                                                                                                                                                        | AN4                                                                                                                         | optional    |
| BankCode                    | bankAccount.bankCode               | Bank Code/BIC in case the transaction is bank related                                                                                                                                                                                                                                                                                                                    | AN12                                                                                                                        | optional    |
| AccountHolder               | bankAccount.holder                 | Account Holder of bank acount                                                                                                                                                                                                                                                                                                                                            | AN128                                                                                                                       | optional    |
| MerchantAccountId           | merchantAccount.id                 | Account ID of Merchant                                                                                                                                                                                                                                                                                                                                                   | AN32 \[a-zA-Z0-9]{32}                                                                                                       | required    |
| MerchantAccountName         | merchantAccount.name               | Name of Merchant                                                                                                                                                                                                                                                                                                                                                         | AN32 \[a-zA-Z0-9]{32}                                                                                                       | optional    |
| UniqueID                    | payment.id                         | Unique ID of payment transaction in gateway                                                                                                                                                                                                                                                                                                                              | AN32 \[a-zA-Z0-9]{32}                                                                                                       | optional    |
| ReconciliationType          | recordType                         | Type of the record                                                                                                                                                                                                                                                                                                                                                       | SETTLED, CHARGEBACK, CHARGEBACK REVERSAL, FEE                                                                               | required    |
| PaymentType                 | transactionType                    | Type of Transaction                                                                                                                                                                                                                                                                                                                                                      | DEBIT, CREDIT, REFUND, BATCH, MONTHLY, SUBMERCHANT, PAYMENT\_FACILITATOR, AUTH\_FEE, CAPTURE\_FEE, CANCEL\_FEE, REFUND\_FEE | required    |
| PspId                       | pspEntityId                        | ID of PSP                                                                                                                                                                                                                                                                                                                                                                | AN32 \[a-zA-Z0-9]{32}                                                                                                       | required    |
| DivisionId                  | divisionEntityId                   | ID of Division                                                                                                                                                                                                                                                                                                                                                           | AN32 \[a-zA-Z0-9]{32}                                                                                                       | optional    |
| MerchantId                  | merchantEntityId                   | ID of Merchant                                                                                                                                                                                                                                                                                                                                                           | AN32 \[a-zA-Z0-9]{32}                                                                                                       | required    |
| ShortId                     | -                                  | Short Id of payment transaction in gateway                                                                                                                                                                                                                                                                                                                               | AN14                                                                                                                        | optional    |
| TransactionId               | merchantTransactionId              | Unique reference number provided by merchant or generated by the gateway                                                                                                                                                                                                                                                                                                 | AN255 \[\s\S]{8,255}                                                                                                        | required    |
| InvoiceId                   | merchantInvoiceId                  | Invoice ID provided by merchant                                                                                                                                                                                                                                                                                                                                          | AN255 \[\s\S]{8,255}                                                                                                        | optional    |
| Amount                      | amount                             | Transaction amount                                                                                                                                                                                                                                                                                                                                                       | N13 \[0-9]{1,10}\\.\[0-9]{2}                                                                                                | required    |
| Currency                    | currency                           | Transaction Currency                                                                                                                                                                                                                                                                                                                                                     | A3 (according to ISO 4217)                                                                                                  | required    |
| Brand                       | paymentBrand                       | Brand of the payment method                                                                                                                                                                                                                                                                                                                                              | A16                                                                                                                         | optional    |
| TxRequestTime               | presentmentDate                    | Time of ordering the transaction by the merchant in Clearing Institute’s time zone. The value can be either retrieved from a specific field in the received settlement file. Or in case no specific field is identified/mapped the default code is utilized which is the timestamp when the acquirer file is parsed on our system. (i.e. the timestamp of the recon job) | ​Content                                                                                                                    | optional    |
| Descriptor                  | descriptor                         | Transaction Reference which appears on the end customer’s statement                                                                                                                                                                                                                                                                                                      | AN128                                                                                                                       | optional    |
| MatchingStatus              | matchedTransactions.status         | The matching status of the corresponding transaction within the gateway                                                                                                                                                                                                                                                                                                  | MATCHED, MULTIPLE\_MATCHES, NOT\_MATCHED                                                                                    | conditional |
| MatchedTransactions         | matchedTransactions.payment\[n].id | Unique ID(s) of the matched transactions                                                                                                                                                                                                                                                                                                                                 | AN32 \[a-zA-Z0-9]{32}                                                                                                       | conditional |
| ChargebackId                | chargebackTransaction.id           | The Unique ID of the Chargeback transaction generated by the gateway after matching a chargeback record.                                                                                                                                                                                                                                                                 | AN32 \[a-zA-Z0-9]{32}                                                                                                       | conditional |

‌

### Card On File <a href="#card-on-file" id="card-on-file"></a>

‌

Following are all the parameters needed for sending card on file transactions.

| Parameter                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Format                                            | Required |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -------- |
| standingInstruction.type                 | <p>The category of the transaction.</p><ul><li><strong>RECURRING</strong>: Recurring Transactions are transactions that are processed on a regular fixed interval for a pre-agreed or advised amount, where applicable. Recurring Transactions don't have a fixed duration and will continue to be processed until the cardholder cancels the agreement.</li><li><strong>INSTALLMENT</strong>: Installment Payments are transactions that are processed on a regular fixed interval for a pre-agreed amount for a single purchase of good or services. Unlike Recurring Transactions, Installment Payments do have a fixed duration and shouldn't continue to be processed after the end of the agreed installment period.</li><li><strong>UNSCHEDULED</strong>: An unscheduled credential-on-file transaction is like a recurring transaction but differs in that it does not happen at pre-agreed intervals. The classic example of such a transaction is when it is triggered by an event such as an amount threshold to ensure that a pay-as-you-go account always has a minimum available reserve.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | UNSCHEDULED\| INSTALLMENT\| RECURRING             | Optional |
| standingInstruction.mode                 | <p>Indicating the mode of subsequent payment transaction.</p><ul><li><strong>INITIAL</strong>: The payment is the first of a series of payments. This first payment must contain additional data like the CVV code or 3D parameters to enable an initial authentication of the request.</li><li><strong>REPEATED</strong>: The payment is a subsequent payment. It may not contain shopper authentication data like the CVV code or 3D parameters - the shopper is not present anymore.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | INITIAL\| REPEATED                                | Optional |
| standingInstruction.source               | <p>Indicating the type of subsequent payment transaction.</p><ul><li><strong>CIT</strong>: Cardholder initiated transaction.</li><li><strong>MIT</strong>: Merchant initiated transaction.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | CIT\| MIT                                         | Optional |
| standingInstruction.initialTransactionId | <p>The value/ID is received as part of the acquirer response of a CIT flagged transaction. Depending on the acquirer the ID is received either in OPP response field:</p><ul><li>'resultDetails.CardholderInitiatedTransactionID'</li><li>Or as one for the ConnectorTxIDs</li><li>The exact OPP response field is documented in the respective Connector integration sheet.</li></ul><p> The ID must be included in all following MIT flagged transaction.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | AN or N (No specific format- Depends on acquirer) | Optional |
| standingInstruction.industryPractice     | <p>The MIT types defined under this category are performed to fulfill a business practice as a follow-up to an original cardholder-merchant interaction that could not be completed with one single transaction.</p><ul><li><strong>INCREMENTAL\_AUTH</strong>: Incremental authorizations can be used to increase the total amount authorized. Incremental authorizations do not replace the original authorization — they are additional to previously authorized amounts — the sum of all linked estimated and incremental authorizations represent the total amount on hold in the cardholder’s account for a given transaction.</li><li><strong>RESUBMISSION</strong>: When a merchant attempts to authorize a transaction after the service has been used but the issuer declines it for insufficient funds, they may attempt to re-authorize to recover the debt. These authorization requests are considered resubmission authorizations and must carry the new “re submission” indicator.</li><li><strong>REAUTHORIZATION</strong>: Re-authorization occurs when a merchant has a need to submit an authorization request after the cardholder has left the point of interaction and there is no possibility of re-authenticating the card or the cardholder. A merchant may need to do this if they intend to split the shipment into multiple deliveries and will only authorize as goods come into stock. If the need to re-authorize occurs, the subsequent authorization requests carry the new “re-authorization” marker and the scheme reference data from the initial interaction.</li><li><strong>DELAYED\_CHARGES and NO\_SHOW</strong>: Such transactions occur largely in the rental and hospitality sectors. These transactions also carry the scheme reference data provided in the initial authorization at the start of the rental or stay agreement as well as in the settlement record.</li></ul> | ​Content                                          | ​Content |


# Reporting Guidelines

(external use)

All reports are a csv file and the timezone UTC at all times.

All reports will be placed on the [SFTP](https://primeiro-pay.gitbook.io/primeiro-pay/connect-to-sftp-1). Reports that have no transactions will be placed on the SFTP but will be empty with no records.

**All Settlement reports are also available as Recon Report to reconcile the previous day or any other given timeframe. See details below the table**

### **Sample Reports:** <a href="#reportingguidelines-externaluse-samplereports" id="reportingguidelines-externaluse-samplereports"></a>

[**MERCHANT\_XXX\_AGGREGATED\_SETTLEMENT\_report\_2018-06-01.csv**](https://primeiropay.atlassian.net/wiki/download/attachments/47874049/MERCHANT_XXX_AGGREGATED_SETTLEMENT_report_2018-06-01.csv?version=1\&modificationDate=1532701024119\&cacheVersion=1\&api=v2)

[**MERCHANT\_XXX\_SETTLEMENT\_CUSTOM\_report\_2018-07-11.csv**](https://primeiropay.atlassian.net/wiki/download/attachments/47874049/MERCHANT_XXX_SETTLEMENT_CUSTOM_report_2018-07-11.csv?version=1\&modificationDate=1532701031943\&cacheVersion=1\&api=v2)

[**MERCHANT\_XXX\_daily\_FRAUDREPORT\_report\_2018-07-27.csv**](https://primeiropay.atlassian.net/wiki/download/attachments/47874049/MERCHANT_XXX_daily_FRAUDREPORT_report_2018-07-27.csv?version=1\&modificationDate=1532701033415\&cacheVersion=1\&api=v2)

[**MERCHANT\_XXX\_daily\_PAYMENT\_report\_2018-07-18.csv**](https://primeiropay.atlassian.net/wiki/download/attachments/47874049/MERCHANT_XXX_daily_PAYMENT_report_2018-07-18.csv?version=1\&modificationDate=1532701035224\&cacheVersion=1\&api=v2)

[**MERCHANT\_XXX\_daily\_CHARGEBACK\_report\_2018-07-18.csv**](https://primeiropay.atlassian.net/wiki/download/attachments/47874049/MERCHANT_XXX_daily_CHARGEBACK_report_2018-07-18.csv?version=1\&modificationDate=1532701036293\&cacheVersion=1\&api=v2)

| Report Type                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Syntax                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Frequency                               | Date / Time Frame                                                                            | Date Range Sample                                                                            | Report generated at time |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------ |
| Settlement Report -31 days                         | <p>This report is being used when the settlement happens after the regular acquirer settlement in Brazil which is 30 days after the transaction has happened.</p><p>At PrimeiroPay we pay you on the 30th day from 3pm UTC to the next day 3pm UTC. As a part of our Transparency policy trading will happen at 3pm UTC daily, so you can monitor the FX rates.</p>                                                                                                                                                                                                                                                                                                                                                                  | <p>MerchantID\_ReportID\_SETTLEMENT\_PREVIOUS\_24\_FULL\_HOURS\_MINUS\_31\_DAYS\_report\_YYYY-MM-DD.csv</p><p><strong>The time stamp in the report name refers to when the transaction happened, not to the date when the report was generated</strong></p><p>Every Monday the report syntax changes to <br>MerchantID\_ReportID\_SETTLEMENT\_PREVIOUS\_72\_FULL\_HOURS\_MINUS\_31\_DAYS\_report\_YYYY-MM-DD.csv</p><p>as there is no FX trading possible during the weekend.</p> | Daily on weekdays after initial 31 days | <p>31 days before report generated</p><p>Timeframe fixed to: 3pm UTC to 3pm UTC next day</p> | <p>Report Date: October 1</p><p>Transaction Date: July 31 3pm UTC to August 1 3pm UTC</p>    | 3.00-3.59pm              |
| Settlement Report previous day                     | <p>As a part of our Transparency policy trading will happen at 3pm UTC daily, so you can monitor the FX rates.</p><p>That means transactions will include transactions from the previous day 3pm to today 3pm</p><p>Fields in a settlement report:<br>Company Account,Merchant Account,Psp Reference,Merchant Reference,Payment Method,Creation Date,TimeZone,Type,Modification Reference,Gross Currency,Gross Debit (GC),Gross Credit (GC),Exchange Rate,Net Currency,Net Debit (NC),Net Credit (NC),Commission (NC),Markup (NC),Scheme Fees (NC),Interchange (NC),Payment Method Variant,Modification Merchant Reference,Batch Number,Installments,Card Holder,Reserved6,Reserved7,Reserved8,Reserved9,Reserved10,TAXSTATEMENT</p> | <p>MerchantID\_ReportID\_SETTLEMENT\_PREVIOUS\_24\_FULL\_HOURS\_report\_YYYY-MM-DD.csv</p><p>Every Monday the report syntax changes to <br>MerchantID\_ReportID\_SETTLEMENT\_PREVIOUS\_72\_FULL\_HOURS\_report\_YYYY-MM-DD.csv</p>                                                                                                                                                                                                                                                | Daily on weekdays                       | Timeframe fixed to: 3pm UTCp previous day to 3pm UTC today                                   | <p>Report Date: October 2</p><p>Transaction Date: October 1 3pm UTC to October 2 3pm UTC</p> | 3.00-3.59pm              |
| Settlement Report previous half month              | <p>Settlement that happens bi-weekly without the 30 day delay of settlement of the acquirer</p><p>Fields in a settlement report:<br>Company Account,Merchant Account,Psp Reference,Merchant Reference,Payment Method,Creation Date,TimeZone,Type,Modification Reference,Gross Currency,Gross Debit (GC),Gross Credit (GC),Exchange Rate,Net Currency,Net Debit (NC),Net Credit (NC),Commission (NC),Markup (NC),Scheme Fees (NC),Interchange (NC),Payment Method Variant,Modification Merchant Reference,Batch Number,Installments,Card Holder,Reserved6,Reserved7,Reserved8,Reserved9,Reserved10,TAXSTATEMENT</p>                                                                                                                   | MerchantID\_ReportID\_SETTLEMENT\_PREVIOUS\_HALF\_MONTH\_report\_YYYY-MM-DD                                                                                                                                                                                                                                                                                                                                                                                                       | Bi-weekly                               | 24hrs                                                                                        | Transactions between October 1 to October 15 when report runs on Oct 16                      | 8.00-8.59am              |
| Settlement Report previous month                   | <p>Settlement that happens for all transactions of the previous month without the 30 day delay of settlement of the acquirer</p><p>Fields in a settlement report:<br>Company Account,Merchant Account,Psp Reference,Merchant Reference,Payment Method,Creation Date,TimeZone,Type,Modification Reference,Gross Currency,Gross Debit (GC),Gross Credit (GC),Exchange Rate,Net Currency,Net Debit (NC),Net Credit (NC),Commission (NC),Markup (NC),Scheme Fees (NC),Interchange (NC),Payment Method Variant,Modification Merchant Reference,Batch Number,Installments,Card Holder,Reserved6,Reserved7,Reserved8,Reserved9,Reserved10,TAXSTATEMENT</p>                                                                                  | MerchantID\_ReportID\_SETTLEMENT\_SETTLEMENT\_PREVIOUS\_MONTH\_report\_YYYY-MM-DD                                                                                                                                                                                                                                                                                                                                                                                                 | monthly, 10th of each month             | 24hrs                                                                                        | All transactions of the previous calendar month                                              | 8.00-8.59am              |
| Settlement Report month before previous month      | <p>Regular settlement term for a full calendar month after funds are received in full from the acquirer for that calendar month</p><p>Fields in a settlement report:<br>Company Account,Merchant Account,Psp Reference,Merchant Reference,Payment Method,Creation Date,TimeZone,Type,Modification Reference,Gross Currency,Gross Debit (GC),Gross Credit (GC),Exchange Rate,Net Currency,Net Debit (NC),Net Credit (NC),Commission (NC),Markup (NC),Scheme Fees (NC),Interchange (NC),Payment Method Variant,Modification Merchant Reference,Batch Number,Installments,Card Holder,Reserved6,Reserved7,Reserved8,Reserved9,Reserved10,TAXSTATEMENT</p>                                                                               | MerchantID\_ReportID\_SETTLEMENT\_MONTH\_BEFORE\_PREVIOUS\_MONTH\_report\_YYYY-MM-DD                                                                                                                                                                                                                                                                                                                                                                                              | monthly, 10th of each month             | 24hrs                                                                                        | <p>Report Date: October 1</p><p>Transaction Date: August 1 to August 31</p>                  | 5.00-5.59pm              |
| Settlement Report half month before previous month | <p>Settlement that happens bi-weekly after the full refunds are received from the acquirer</p><p>Fields in a settlement report:<br>Company Account,Merchant Account,Psp Reference,Merchant Reference,Payment Method,Creation Date,TimeZone,Type,Modification Reference,Gross Currency,Gross Debit (GC),Gross Credit (GC),Exchange Rate,Net Currency,Net Debit (NC),Net Credit (NC),Commission (NC),Markup (NC),Scheme Fees (NC),Interchange (NC),Payment Method Variant,Modification Merchant Reference,Batch Number,Installments,Card Holder,Reserved6,Reserved7,Reserved8,Reserved9,Reserved10,TAXSTATEMENT</p>                                                                                                                    | MerchantID\_ReportID\_SETTLEMENT\_PREVIOUS\_PREVIOUS\_PREVIOUS\_HALF\_MONTH\_report\_YYYY-MM-DD                                                                                                                                                                                                                                                                                                                                                                                   | Bi-weekly                               | 24hrs                                                                                        | <p>Report Date: October 1</p><p>Transaction Date: August 16 to August 31</p>                 | 9.00-9.59am              |
| Chargeback & Refund Report                         | <p>The chargeback report is a report that contains all Chargebacks and Refunds to reconsile / treat them. Refunds also may happen due to Fraud Alerts (see below)</p><p>Fields in a payment reports:</p><p>PSP Transaction ID, Merchant Transaction ID, Payment Brand, Purchase Amount, Purchase Currency, Net Amount Net, Currency Transaction, Timestamp, Country Code, Refund Reason</p>                                                                                                                                                                                                                                                                                                                                          | Merchantname\_ReportID\_daily\_CHARGEBACK\_report\_YYYY-MM-DD                                                                                                                                                                                                                                                                                                                                                                                                                     | Daily                                   | Previous day (24hrs)                                                                         | <p>Report Date October 2</p><p>Transaction Date: October 1 00.00 UTC to 23.59 UTC</p>        | 7.00-7.59am UTC          |
| Payment Report                                     | <p>The payment report gives an overview about successful transactions of the previous day. It does not contain any information on Foreign Exchange, Commission (Processing Fee) or any other additional information a Settlement Report provides.</p><p>Fields in a payment reports:</p><p>PSP Transaction ID, Merchant Transaction ID, Payment Brand, Purchase Amount, Purchase Currency, Net Amount Net, Currency Transaction, Timestamp, Country Code</p>                                                                                                                                                                                                                                                                         | Merchantname\_ReportID\_daily\_PAYMENT\_report\_YYYY-MM-DD                                                                                                                                                                                                                                                                                                                                                                                                                        | Daily                                   | Previous day (24hrs)                                                                         | <p>Report Date October 2</p><p>Transaction Date: October 1 00.00 UTC to 23.59 UTC</p>        | 5.00-5.59am UTC          |
| Aggregated Settlement Report                       | While the Settlement Report provides this for each settlement batch on a transaction level (for each merchant account), the aggregate settlement report can be run both on merchant account and company account level. It includes all batches closed in the chosen period, summarized by merchant account, store, payment method, the day of sale and settlement batch.                                                                                                                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | any                                     |                                                                                              |                                                                                              |                          |

### Settlement / Recon Report Fields: <a href="#reportingguidelines-externaluse-settlement-reconreportfields" id="reportingguidelines-externaluse-settlement-reconreportfields"></a>

If the field value is null it means it is empty and will never be filled.

\
Company Account: Your MerchantID with PrimeiroPay\
Merchant Account: Your MerchantID with PrimeiroPay\
Psp Reference: Our Unique ID for this transaction\
Merchant Reference: Your TransactionID\
Alt Merchant Reference: In case of Adyen, you will see your TransactionID here and Adyen's PSP Reference in the Merchant Reference\
Payment Method: Card Brands such as VISA, MASTER, AMEX, ELO\
Creation Date: Transaction Time Stamp of the transaction\
TimeZone: UTC\
Type: settled, refunded or chargeback (in case of Recon report: sentforsettle)\
Modification Reference: In case of a Refund or Chargeback you will see here the PSP Reference of the original transaction\
Gross Currency: BRL\
Gross Debit (GC): Value in XX.XX for Chargebacks and Refunds\
Gross Credit (GC): Vlaue in XX.XX for Successful transactions\
Exchange Rate: Exchange Rate applied for this transaction\
Net Currency: Your Payout Currency, e.g. EUR, USD, GPB, BRL, ...\
Net Debit (NC): Deduction of Chargebacks and Refunds from your Payout in your Net Currency\
Net Credit (NC): Payout to you in your Net Currency after our Commission\
Commission (NC): Our Commission in Net Currency\
Markup (NC): Markup charges of us in Net Currency if applicable\
Brazilian Taxes (NC): In case of domestic merchants that get settled locally, the applicable taxes will be shown here\
Interchange (NC): null\
Payment Method Variant: Same as Payment Method\
Modification Merchant Reference: same as Modification Reference\
Batch Number: Batch number that will be used for settlement to you\
Installments: Number of Installments used\
Card Holder: Name of the Card holder\
Reserved6: null\
Reserved7: null\
Reserved8: null\
Reserved9: null\
Reserved10: null\
TAXSTATEMENT: Tax Identification number of the shopper, in case of Brazil "CPF"

### Payment Report Fields: <a href="#reportingguidelines-externaluse-paymentreportfields" id="reportingguidelines-externaluse-paymentreportfields"></a>

PSP Transaction ID: Our Unique transactionID \
Merchant Transaction ID: Your TransactionID\
Payment Brand: Card Brands such as VISA, MASTER, AMEX, ELO\
Purchase Amount: Gross Amount in BRL\
Purchase Currency: BRL\
Net Amount: Payout in BRL after our commission\
Net Currency : BRL\
Transaction Timestamp: Time of the transaction, in case of Refund or chargeback, time of chargeback or Refund\
Country Code: provided by the merchant

### Chargeback Report Fields: <a href="#reportingguidelines-externaluse-chargebackreportfields" id="reportingguidelines-externaluse-chargebackreportfields"></a>

PSP Transaction ID: Our Unique transactionID \
Merchant Transaction ID: Your TransactionID\
Payment Brand: Card Brands such as VISA, MASTER, AMEX, ELO\
Purchase Amount: Gross Amount in BRL\
Purchase Currency: BRL\
Net Amount: Payout in BRL after our commission\
Net Currency : BRL\
Transaction Timestamp: Time of the transaction, in case of Refund or chargeback, time of chargeback or Refund\
Country Code: provided by the merchant\
Refund Reason: In case you have activated the Fraud Alert with PrimeiroPay, there will be a value "Fraud Alert" with every Refund that were refunded by PrimeiroPay because of a Fraud Alert.


# Result Codes

&#x20; The result codes are part of the response body's JSON (field `result`) containing a `code` and a `description` explaining the code.

* [Structure of result codes](https://developers.primeiropay.com/untitled#structure-of-result-codes)
* [Complete list of result codes](https://developers.primeiropay.com/result-codes#complete-list-of-result-codes)
* [Result codes for successful and pending transactions](https://developers.primeiropay.com/untitled#result-codes-for-successful-and-pending-transactions)
* [Result codes for rejected transactions](https://developers.primeiropay.com/untitled#result-codes-for-rejected-transactions)
* [Rejections specific to risk handling](https://developers.primeiropay.com/untitled#rejections-specific-to-risk-handling)
* [Result codes for rejections due to validation](https://developers.primeiropay.com/untitled#result-codes-for-rejections-due-to-validation)
* [Chargeback related result codes](https://developers.primeiropay.com/untitled#chargeback-related-result-codes)

### Structure of result codes

A result code has the format `ddd.ddd.ddd`, i.e. 3 groups of 3-digit numbers. The codes are split into rough groups by the first number, then into more detailed sub-groups by the second number, then into the exact code by the third number.

Example: `800.100.153` means: `800` -> Bank declined, `100` -> it declined the authorization, `153` -> it declined authorization because the CVV is wrong

### Complete list of result codes

You can pull a JSON with the result codes as listed in the table below by sending a GET request to <https://test.oppwa.com/v1/resultcodes>.

In many cases however you don't need the precise evaluation for each and every code, but just for a certain subgroup. Therefore the following list presents the result codes in a grouped way that you typically can evaluate by just taking the first two number-groups.

### Result codes for successful and pending transactions

#### Result codes for successfully processed transactions

The regular expression pattern for filtering out this group is: `/^(000\.000\.|000\.100\.1|000\.[36])/`

| Result Code | Result Description                                                   |
| ----------- | -------------------------------------------------------------------- |
| 000.000.000 | Transaction succeeded                                                |
| 000.000.100 | successful request                                                   |
| 000.100.105 | Chargeback Representment is successful                               |
| 000.100.106 | Chargeback Representment cancellation is successful                  |
| 000.100.110 | Request successfully processed in 'Merchant in Integrator Test Mode' |
| 000.100.111 | Request successfully processed in 'Merchant in Validator Test Mode'  |
| 000.100.112 | Request successfully processed in 'Merchant in Connector Test Mode'  |
| 000.300.000 | Two-step transaction succeeded                                       |
| 000.300.100 | Risk check successful                                                |
| 000.300.101 | Risk bank account check successful                                   |
| 000.300.102 | Risk report successful                                               |
| 000.310.100 | Account updated                                                      |
| 000.310.101 | Account updated (Credit card expired)                                |
| 000.310.110 | No updates found, but account is valid                               |
| 000.600.000 | transaction succeeded due to external update                         |

#### Result codes for successfully processed transactions that should be manually reviewed

The regular expression pattern for filtering out this group is: `/^(000\.400\.0[^3]|000\.400\.100)/`

| Result Code | Result Description                                                                                          |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| 000.400.000 | Transaction succeeded (please review manually due to fraud suspicion)                                       |
| 000.400.010 | Transaction succeeded (please review manually due to AVS return code)                                       |
| 000.400.020 | Transaction succeeded (please review manually due to CVV return code)                                       |
| 000.400.040 | Transaction succeeded (please review manually due to amount mismatch)                                       |
| 000.400.050 | Transaction succeeded (please review manually because transaction is pending)                               |
| 000.400.060 | Transaction succeeded (approved at merchant's risk)                                                         |
| 000.400.070 | Transaction succeeded (waiting for external risk review)                                                    |
| 000.400.080 | Transaction succeeded (please review manually because the service was unavailable)                          |
| 000.400.081 | Transaction succeeded (please review manually, as the risk status not available yet due network timeout)    |
| 000.400.082 | Transaction succeeded (please review manually, as the risk status not available yet due processing timeout) |
| 000.400.090 | Transaction succeeded (please review manually due to external risk check)                                   |
| 000.400.100 | Transaction succeeded, risk after payment rejected                                                          |

#### Result codes for pending transactions

The regular expression pattern for filtering out this group is: `/^(000\.200)/`. These codes mean that there is an open session in the background, meaning within half an hour there will be a status change, if nothing else happens, to timeout.

| Result Code | Result Description                                            |
| ----------- | ------------------------------------------------------------- |
| 000.200.000 | transaction pending                                           |
| 000.200.001 | Transaction pending for acquirer, the consumer is not present |
| 000.200.100 | successfully created checkout                                 |
| 000.200.101 | successfully updated checkout                                 |
| 000.200.102 | successfully deleted checkout                                 |
| 000.200.103 | checkout is pending                                           |
| 000.200.200 | Transaction initialized                                       |

There is another kind of pending regular expression pattern for filtering out this group is: `/^(800\.400\.5|100\.400\.500)/`. These codes describe a situation where the status of a transaction can change even after several days.

| Result Code | Result Description                                               |
| ----------- | ---------------------------------------------------------------- |
| 100.400.500 | waiting for external risk                                        |
| 800.400.500 | Waiting for confirmation of non-instant payment. Denied for now. |
| 800.400.501 | Waiting for confirmation of non-instant debit. Denied for now.   |
| 800.400.502 | Waiting for confirmation of non-instant refund. Denied for now.  |

### Result codes for rejected transactions

#### Result codes for rejections due to 3Dsecure and Intercard risk checks

The regular expression pattern for filtering out this group is: `/^(000\.400\.[1][0-9][1-9]|000\.400\.2)/`

| Result Code | Result Description                                                                   |
| ----------- | ------------------------------------------------------------------------------------ |
| 000.400.101 | card not participating/authentication unavailable                                    |
| 000.400.102 | user not enrolled                                                                    |
| 000.400.103 | Technical Error in 3D system                                                         |
| 000.400.104 | Missing or malformed 3DSecure Configuration for Channel                              |
| 000.400.105 | Unsupported User Device - Authentication not possible                                |
| 000.400.106 | invalid payer authentication response(PARes) in 3DSecure Transaction                 |
| 000.400.107 | Communication Error to VISA/Mastercard Directory Server                              |
| 000.400.108 | Cardholder Not Found - card number provided is not found in the ranges of the issuer |
| 000.400.109 | Card is not enrolled for 3DS version 2                                               |
| 000.400.200 | risk management check communication error                                            |

#### Result codes for rejections by the external bank or similar payment system

The regular expression pattern for filtering out this group is: `/^(800\.[17]00|800\.800\.[123])/`

| Result Code | Result Description                                                                                                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 800.100.100 | transaction declined for unknown reason                                                                                                                                                                       |
| 800.100.150 | transaction declined (refund on gambling tx not allowed)                                                                                                                                                      |
| 800.100.151 | transaction declined (invalid card)                                                                                                                                                                           |
| 800.100.152 | transaction declined by authorization system                                                                                                                                                                  |
| 800.100.153 | transaction declined (invalid CVV)                                                                                                                                                                            |
| 800.100.154 | transaction declined (transaction marked as invalid)                                                                                                                                                          |
| 800.100.155 | transaction declined (amount exceeds credit)                                                                                                                                                                  |
| 800.100.156 | transaction declined (format error)                                                                                                                                                                           |
| 800.100.157 | transaction declined (wrong expiry date)                                                                                                                                                                      |
| 800.100.158 | transaction declined (suspecting manipulation)                                                                                                                                                                |
| 800.100.159 | transaction declined (stolen card)                                                                                                                                                                            |
| 800.100.160 | transaction declined (card blocked)                                                                                                                                                                           |
| 800.100.161 | transaction declined (too many invalid tries)                                                                                                                                                                 |
| 800.100.162 | transaction declined (limit exceeded)                                                                                                                                                                         |
| 800.100.163 | transaction declined (maximum transaction frequency exceeded)                                                                                                                                                 |
| 800.100.164 | transaction declined (merchants limit exceeded)                                                                                                                                                               |
| 800.100.165 | transaction declined (card lost)                                                                                                                                                                              |
| 800.100.166 | transaction declined (Incorrect personal identification number)                                                                                                                                               |
| 800.100.167 | transaction declined (referencing transaction does not match)                                                                                                                                                 |
| 800.100.168 | transaction declined (restricted card)                                                                                                                                                                        |
| 800.100.169 | transaction declined (card type is not processed by the authorization center)                                                                                                                                 |
| 800.100.170 | transaction declined (transaction not permitted)                                                                                                                                                              |
| 800.100.171 | transaction declined (pick up card)                                                                                                                                                                           |
| 800.100.172 | transaction declined (account blocked)                                                                                                                                                                        |
| 800.100.173 | transaction declined (invalid currency, not processed by authorization center)                                                                                                                                |
| 800.100.174 | transaction declined (invalid amount)                                                                                                                                                                         |
| 800.100.175 | transaction declined (invalid brand)                                                                                                                                                                          |
| 800.100.176 | transaction declined (account temporarily not available. Please try again later)                                                                                                                              |
| 800.100.177 | transaction declined (amount field should not be empty)                                                                                                                                                       |
| 800.100.178 | transaction declined (PIN entered incorrectly too often)                                                                                                                                                      |
| 800.100.179 | transaction declined (exceeds withdrawal count limit)                                                                                                                                                         |
| 800.100.190 | transaction declined (invalid configuration data)                                                                                                                                                             |
| 800.100.191 | transaction declined (transaction in wrong state on aquirer side)                                                                                                                                             |
| 800.100.192 | transaction declined (invalid CVV, Amount has still been reserved on the customer's card and will be released in a few business days. Please ensure the CVV code is accurate before retrying the transaction) |
| 800.100.195 | transaction declined (UserAccount Number/ID unknown)                                                                                                                                                          |
| 800.100.196 | transaction declined (registration error)                                                                                                                                                                     |
| 800.100.197 | transaction declined (registration cancelled externally)                                                                                                                                                      |
| 800.100.198 | transaction declined (invalid holder)                                                                                                                                                                         |
| 800.100.199 | transaction declined (invalid tax number)                                                                                                                                                                     |
| 800.100.200 | Refer to Payer due to reason not specified                                                                                                                                                                    |
| 800.100.201 | Account or Bank Details Incorrect                                                                                                                                                                             |
| 800.100.202 | Account Closed                                                                                                                                                                                                |
| 800.100.203 | Insufficient Funds                                                                                                                                                                                            |
| 800.100.204 | Mandate Expired                                                                                                                                                                                               |
| 800.100.205 | Mandate Discarded                                                                                                                                                                                             |
| 800.100.206 | Refund of an authorized payment requested by the customer                                                                                                                                                     |
| 800.100.207 | Refund requested                                                                                                                                                                                              |
| 800.100.208 | Direct debit not enabled for the specified account or bank                                                                                                                                                    |
| 800.100.402 | cc/bank account holder not valid                                                                                                                                                                              |
| 800.100.403 | transaction declined (revocation of authorisation order)                                                                                                                                                      |
| 800.100.500 | Card holder has advised his bank to stop this recurring payment                                                                                                                                               |
| 800.100.501 | Card holder has advised his bank to stop all recurring payments for this merchant                                                                                                                             |
| 800.700.100 | transaction for the same session is currently being processed, please try again later.                                                                                                                        |
| 800.700.101 | family name too long                                                                                                                                                                                          |
| 800.700.201 | given name too long                                                                                                                                                                                           |
| 800.700.500 | company name too long                                                                                                                                                                                         |
| 800.800.102 | Invalid street                                                                                                                                                                                                |
| 800.800.202 | Invalid zip                                                                                                                                                                                                   |
| 800.800.302 | Invalid city                                                                                                                                                                                                  |

#### Result codes for rejections due to communication errors

The regular expression pattern for filtering out this group is: `/^(900\.[1234]00|000\.400\.030)/`

| Result Code | Result Description                                                                                    |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| 000.400.030 | Transaction partially failed (please reverse manually due to failed automatic reversal)               |
| 900.100.100 | unexpected communication error with connector/acquirer                                                |
| 900.100.200 | error response from connector/acquirer                                                                |
| 900.100.201 | error on the external gateway (e.g. on the part of the bank, acquirer,...)                            |
| 900.100.202 | invalid transaction flow, the requested function is not applicable for the referenced transaction.    |
| 900.100.203 | error on the internal gateway                                                                         |
| 900.100.300 | timeout, uncertain result                                                                             |
| 900.100.301 | Transaction timed out without response from connector/acquirer. It was reversed.                      |
| 900.100.310 | Transaction timed out due to internal system misconfiguration. Request to acquirer has not been sent. |
| 900.100.400 | timeout at connectors/acquirer side                                                                   |
| 900.100.500 | timeout at connectors/acquirer side (try later)                                                       |
| 900.100.600 | connector/acquirer currently down                                                                     |
| 900.200.100 | Message Sequence Number of Connector out of sync                                                      |
| 900.300.600 | user session timeout                                                                                  |
| 900.400.100 | unexpected communication error with external risk provider                                            |

#### Result codes for rejections due to system errors

The regular expression pattern for filtering out this group is: `/^(800\.[56]|999\.|600\.1|800\.800\.[84])/`

| Result Code | Result Description                                                                                                                                                                                          |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 600.100.100 | Unexpected Integrator Error (Request could not be processed)                                                                                                                                                |
| 800.500.100 | direct debit transaction declined for unknown reason                                                                                                                                                        |
| 800.500.110 | Unable to process transaction - ran out of terminalIds - please contact acquirer                                                                                                                            |
| 800.600.100 | transaction is being already processed                                                                                                                                                                      |
| 800.800.400 | Connector/acquirer system is under maintenance                                                                                                                                                              |
| 800.800.800 | The payment system is currenty unavailable, please contact support in case this happens again.                                                                                                              |
| 800.800.801 | The payment system is currenty unter maintenance. Please apologize for the inconvenience this may cause. If you were not informed of this maintenance window in advance, contact your sales representative. |
| 999.999.888 | UNDEFINED PLATFORM DATABASE ERROR                                                                                                                                                                           |
| 999.999.999 | UNDEFINED CONNECTOR/ACQUIRER ERROR                                                                                                                                                                          |

#### Result codes for rejections due to error in asynchonous workflow

The regular expression pattern for filtering out this group is: `/^(100\.39[765])/`

| Result Code | Result Description                                            |
| ----------- | ------------------------------------------------------------- |
| 100.395.101 | Bank not supported for Giropay                                |
| 100.395.102 | Account not enabled for Giropay e.g. test account             |
| 100.395.501 | Previously pending online transfer transaction timed out      |
| 100.395.502 | Acquirer/Bank reported timeout on online transfer transaction |
| 100.396.101 | Cancelled by user                                             |
| 100.396.102 | Not confirmed by user                                         |
| 100.396.103 | Previously pending transaction timed out                      |
| 100.396.104 | Uncertain status - probably cancelled by user                 |
| 100.396.106 | User did not agree to payment method terms                    |
| 100.396.201 | Cancelled by merchant                                         |
| 100.397.101 | Cancelled by user due to external update                      |
| 100.397.102 | Rejected by connector/acquirer due to external update         |

#### Result codes for Soft Declines

The regular expression pattern for filtering out this group is: `/^(300\.100\.100)/`

| Result Code | Result Description                                                 |
| ----------- | ------------------------------------------------------------------ |
| 300.100.100 | Transaction declined (additional customer authentication required) |

### Rejections specific to risk handling

#### Result codes for rejections due to checks by external risk systems

The regular expression pattern for filtering out this group is: `/^(100\.400\.[0-3]|100\.38|100\.370\.100|100\.370\.11)/`

| Result Code | Result Description                                                                |
| ----------- | --------------------------------------------------------------------------------- |
| 100.370.100 | transaction declined                                                              |
| 100.370.110 | transaction must be executed for German address                                   |
| 100.370.111 | system error( possible incorrect/missing input data)                              |
| 100.380.100 | transaction declined                                                              |
| 100.380.101 | transaction contains no risk management part                                      |
| 100.380.110 | transaction must be executed for German address                                   |
| 100.380.201 | no risk management process type specified                                         |
| 100.380.305 | no frontend information provided for asynchronous transaction                     |
| 100.380.306 | no authentication data provided in risk management transaction                    |
| 100.380.401 | User Authentication Failed                                                        |
| 100.380.501 | risk management transaction timeout                                               |
| 100.400.000 | transaction declined (Wrong Address)                                              |
| 100.400.001 | transaction declined (Wrong Identification)                                       |
| 100.400.002 | transaction declined (Insufficient credibility score)                             |
| 100.400.005 | transaction must be executed for German address                                   |
| 100.400.007 | System error ( possible incorrect/missing input data)                             |
| 100.400.020 | transaction declined                                                              |
| 100.400.021 | transaction declined for country                                                  |
| 100.400.030 | transaction not authorized. Please check manually                                 |
| 100.400.039 | transaction declined for other error                                              |
| 100.400.040 | authorization failure                                                             |
| 100.400.041 | transaction must be executed for German address                                   |
| 100.400.042 | transaction declined by SCHUFA (Insufficient credibility score)                   |
| 100.400.043 | transaction declined because of missing obligatory parameter(s)                   |
| 100.400.044 | transaction not authorized. Please check manually                                 |
| 100.400.045 | SCHUFA result not definite. Please check manually                                 |
| 100.400.051 | SCHUFA system error (possible incorrect/missing input data)                       |
| 100.400.060 | authorization failure                                                             |
| 100.400.061 | transaction declined (Insufficient credibility score)                             |
| 100.400.063 | transaction declined because of missing obligatory parameter(s)                   |
| 100.400.064 | transaction must be executed for Austrian, German or Swiss address                |
| 100.400.065 | result ambiguous. Please check manually                                           |
| 100.400.071 | system error (possible incorrect/missing input data)                              |
| 100.400.080 | authorization failure                                                             |
| 100.400.081 | transaction declined                                                              |
| 100.400.083 | transaction declined because of missing obligatory parameter(s)                   |
| 100.400.084 | transaction can not be executed for given country                                 |
| 100.400.085 | result ambiguous. Please check manually                                           |
| 100.400.086 | transaction declined (Wrong Address)                                              |
| 100.400.087 | transaction declined (Wrong Identification)                                       |
| 100.400.091 | system error (possible incorrect/missing input data)                              |
| 100.400.100 | transaction declined - very bad rating                                            |
| 100.400.120 | authorization failure                                                             |
| 100.400.121 | account blacklisted                                                               |
| 100.400.122 | transaction must be executed for valid German account                             |
| 100.400.123 | transaction declined because of missing obligatory parameter(s)                   |
| 100.400.130 | system error (possible incorrect/missing input data)                              |
| 100.400.139 | system error (possible incorrect/missing input data)                              |
| 100.400.140 | transaction declined by GateKeeper                                                |
| 100.400.141 | Challenge by ReD Shield                                                           |
| 100.400.142 | Deny by ReD Shield                                                                |
| 100.400.143 | Noscore by ReD Shield                                                             |
| 100.400.144 | ReD Shield data error                                                             |
| 100.400.145 | ReD Shield connection error                                                       |
| 100.400.146 | Line item error by ReD Shield                                                     |
| 100.400.147 | Payment void and transaction denied by ReD Shield                                 |
| 100.400.148 | Payment void and transaction challenged by ReD Shield                             |
| 100.400.149 | Payment void and data error by ReD Shield                                         |
| 100.400.150 | Payment void and connection error by ReD Shield                                   |
| 100.400.151 | Payment void and line item error by ReD Shield                                    |
| 100.400.152 | Payment void and error returned by ReD Shield                                     |
| 100.400.241 | Challenged by Threat Metrix                                                       |
| 100.400.242 | Denied by Threat Metrix                                                           |
| 100.400.243 | Invalid sessionId                                                                 |
| 100.400.260 | authorization failure                                                             |
| 100.400.300 | abort checkout process                                                            |
| 100.400.301 | reenter age/birthdate                                                             |
| 100.400.302 | reenter address (packstation not allowed)                                         |
| 100.400.303 | reenter address                                                                   |
| 100.400.304 | invalid input data                                                                |
| 100.400.305 | invalid foreign address                                                           |
| 100.400.306 | delivery address error                                                            |
| 100.400.307 | offer only secure methods of payment                                              |
| 100.400.308 | offer only secure methods of payment; possibly abort checkout                     |
| 100.400.309 | confirm corrected address; if not confirmed, offer secure methods of payment only |
| 100.400.310 | confirm bank account data; if not confirmed, offer secure methods of payment only |
| 100.400.311 | transaction declined (format error)                                               |
| 100.400.312 | transaction declined (invalid configuration data)                                 |
| 100.400.313 | currency field is invalid or missing                                              |
| 100.400.314 | amount invalid or empty                                                           |
| 100.400.315 | invalid or missing email address (probably invalid syntax)                        |
| 100.400.316 | transaction declined (card missing)                                               |
| 100.400.317 | transaction declined (invalid card)                                               |
| 100.400.318 | invalid IP number                                                                 |
| 100.400.319 | transaction declined by risk system                                               |
| 100.400.320 | shopping cart data invalid or missing                                             |
| 100.400.321 | payment type invalid or missing                                                   |
| 100.400.322 | encryption method invalid or missing                                              |
| 100.400.323 | certificate invalid or missing                                                    |
| 100.400.324 | Error on the external risk system                                                 |
| 100.400.325 | External risk system not available                                                |
| 100.400.326 | Risk bank account check unsuccessful                                              |
| 100.400.327 | Risk report unsuccessful                                                          |
| 100.400.328 | Risk report unsuccessful (invalid data)                                           |

#### Result codes for rejections due to address validation

The regular expression pattern for filtering out this group is: `/^(800\.400\.1)/`

| Result Code | Result Description                                                                                                                                                                                  |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 800.400.100 | AVS Check Failed                                                                                                                                                                                    |
| 800.400.101 | Mismatch of AVS street value                                                                                                                                                                        |
| 800.400.102 | Mismatch of AVS street number                                                                                                                                                                       |
| 800.400.103 | Mismatch of AVS PO box value fatal                                                                                                                                                                  |
| 800.400.104 | Mismatch of AVS zip code value fatal                                                                                                                                                                |
| 800.400.105 | Mismatch of AVS settings (AVSkip, AVIgnore, AVSRejectPolicy) value                                                                                                                                  |
| 800.400.110 | AVS Check Failed. Amount has still been reserved on the customer's card and will be released in a few business days. Please ensure the billing address is accurate before retrying the transaction. |
| 800.400.150 | Implausible address data                                                                                                                                                                            |
| 800.400.151 | Implausible address state data                                                                                                                                                                      |

#### Result codes for rejections due to 3Dsecure

The regular expression pattern for filtering out this group is: `/^(800\.400\.2|100\.380\.4|100\.390)/`

| Result Code | Result Description                                                                            |
| ----------- | --------------------------------------------------------------------------------------------- |
| 100.380.401 | User Authentication Failed                                                                    |
| 100.390.101 | purchase amount/currency mismatch                                                             |
| 100.390.102 | PARes Validation failed                                                                       |
| 100.390.103 | PARes Validation failed - problem with signature                                              |
| 100.390.104 | XID mismatch                                                                                  |
| 100.390.105 | Transaction rejected because of technical error in 3DSecure system                            |
| 100.390.106 | Transaction rejected because of error in 3DSecure configuration                               |
| 100.390.107 | Transaction rejected because cardholder authentication unavailable                            |
| 100.390.108 | Transaction rejected because merchant not participating in 3DSecure program                   |
| 100.390.109 | Transaction rejected because of VISA status 'U' or AMEX status 'N' or 'U' in 3DSecure program |
| 100.390.110 | Cardholder Not Found - card number provided is not found in the ranges of the issuer          |
| 100.390.111 | Communication Error to VISA/Mastercard Directory Server                                       |
| 100.390.112 | Technical Error in 3D system                                                                  |
| 100.390.113 | Unsupported User Device - Authentication not possible                                         |
| 100.390.115 | Authentication failed due to invalid message format                                           |
| 100.390.116 | Access denied to the authentication system                                                    |
| 100.390.117 | Authentication failed due to invalid data fields                                              |
| 800.400.200 | Invalid Payer Authentication in 3DSecure transaction                                          |

#### Result codes for rejections due to blacklist validation

The regular expression pattern for filtering out this group is: `/^(100\.100\.701|800\.[32])/`

| Result Code | Result Description                                                     |
| ----------- | ---------------------------------------------------------------------- |
| 100.100.701 | suspecting fraud, this card may not be processed                       |
| 800.200.159 | account or user is blacklisted (card stolen)                           |
| 800.200.160 | account or user is blacklisted (card blocked)                          |
| 800.200.165 | account or user is blacklisted (card lost)                             |
| 800.200.202 | account or user is blacklisted (account closed)                        |
| 800.200.208 | account or user is blacklisted (account blocked)                       |
| 800.200.220 | account or user is blacklisted (fraudulent transaction)                |
| 800.300.101 | account or user is blacklisted                                         |
| 800.300.102 | country blacklisted                                                    |
| 800.300.200 | email is blacklisted                                                   |
| 800.300.301 | ip blacklisted                                                         |
| 800.300.302 | ip is anonymous proxy                                                  |
| 800.300.401 | bin blacklisted                                                        |
| 800.300.500 | transaction temporary blacklisted (too many tries invalid CVV)         |
| 800.300.501 | transaction temporary blacklisted (too many tries invalid expire date) |
| 800.310.200 | Account closed                                                         |
| 800.310.210 | Account not found                                                      |
| 800.310.211 | Account not found (BIN/issuer not participating)                       |

#### Result codes for rejections due to risk validation

The regular expression pattern for filtering out this group is: `/^(800\.1[123456]0)/`

| Result Code | Result Description                                                                 |
| ----------- | ---------------------------------------------------------------------------------- |
| 800.110.100 | duplicate transaction                                                              |
| 800.120.100 | Rejected by Throttling.                                                            |
| 800.120.101 | maximum number of transactions per account already exceeded                        |
| 800.120.102 | maximum number of transactions per ip already exceeded                             |
| 800.120.103 | maximum number of transactions per email already exceeded                          |
| 800.120.200 | maximum total volume of transactions already exceeded                              |
| 800.120.201 | maximum total volume of transactions per account already exceeded                  |
| 800.120.202 | maximum total volume of transactions per ip already exceeded                       |
| 800.120.203 | maximum total volume of transactions per email already exceeded                    |
| 800.120.300 | chargeback rate per bin exceeded                                                   |
| 800.120.401 | maximum number of transactions or total volume for configured MIDs or CIs exceeded |
| 800.130.100 | Transaction with same TransactionId already exists                                 |
| 800.140.100 | maximum number of registrations per mobile number exceeded                         |
| 800.140.101 | maximum number of registrations per email address exceeded                         |
| 800.140.110 | maximum number of registrations of mobile per credit card number exceeded          |
| 800.140.111 | maximum number of registrations of credit card number per mobile exceeded          |
| 800.140.112 | maximum number of registrations of email per credit card number exceeded           |
| 800.140.113 | maximum number of registrations of credit card number per email exceeded           |
| 800.150.100 | Account Holder does not match Customer Name                                        |
| 800.160.100 | Invalid payment data for configured Shopper Dispatching Type                       |
| 800.160.110 | Invalid payment data for configured Payment Dispatching Type                       |
| 800.160.120 | Invalid payment data for configured Recurring Transaction Dispatching Type         |
| 800.160.130 | Invalid payment data for configured TicketSize Dispatching Type                    |

### Result codes for rejections due to validation

#### Result codes for rejections due to configuration validation

The regular expression pattern for filtering out this group is: `/^(600\.[23]|500\.[12]|800\.121)/`

| Result Code | Result Description                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| 500.100.201 | Channel/Merchant is disabled (no processing possible)                                                               |
| 500.100.202 | Channel/Merchant is new (no processing possible yet)                                                                |
| 500.100.203 | Channel/Merchant is closed (no processing possible)                                                                 |
| 500.100.301 | Merchant-Connector is disabled (no processing possible)                                                             |
| 500.100.302 | Merchant-Connector is new (no processing possible yet)                                                              |
| 500.100.303 | Merchant-Connector is closed (no processing possible)                                                               |
| 500.100.304 | Merchant-Connector is disabled at gateway (no processing possible)                                                  |
| 500.100.401 | Connector is unavailable (no processing possible)                                                                   |
| 500.100.402 | Connector is new (no processing possible yet)                                                                       |
| 500.100.403 | Connector is unavailable (no processing possible)                                                                   |
| 500.200.101 | No target account configured for DD transaction                                                                     |
| 600.200.100 | invalid Payment Method                                                                                              |
| 600.200.200 | Unsupported Payment Method                                                                                          |
| 600.200.201 | Channel/Merchant not configured for this payment method                                                             |
| 600.200.202 | Channel/Merchant not configured for this payment type                                                               |
| 600.200.300 | invalid Payment Type                                                                                                |
| 600.200.310 | invalid Payment Type for given Payment Method                                                                       |
| 600.200.400 | Unsupported Payment Type                                                                                            |
| 600.200.500 | Invalid payment data. You are not configured for this currency or sub type (country or brand)                       |
| 600.200.501 | Invalid payment data for Recurring transaction. Merchant or transaction data has wrong recurring configuration.     |
| 600.200.600 | invalid payment code (type or method)                                                                               |
| 600.200.700 | invalid payment mode (you are not configured for the requested transaction mode)                                    |
| 600.200.800 | invalid brand for given payment method and payment mode (you are not configured for the requested transaction mode) |
| 600.200.810 | invalid return code provided                                                                                        |
| 600.300.101 | Merchant key not found                                                                                              |
| 600.300.200 | merchant source IP address not whitelisted                                                                          |
| 600.300.210 | merchant notificationUrl not whitelisted                                                                            |
| 600.300.211 | shopperResultUrl not whitelisted                                                                                    |
| 800.121.100 | Channel not configured for given source type. Please contact your account manager.                                  |
| 800.121.200 | Secure Query is not enabled for this entity. Please contact your account manager.                                   |

#### Result codes for rejections due to registration validation

The regular expression pattern for filtering out this group is: `/^(100\.[13]50)/`

| Result Code | Result Description                                                                      |
| ----------- | --------------------------------------------------------------------------------------- |
| 100.150.100 | request contains no Account data and no registration id                                 |
| 100.150.101 | invalid format for specified registration id (must be uuid format)                      |
| 100.150.200 | registration does not exist                                                             |
| 100.150.201 | registration is not confirmed yet                                                       |
| 100.150.202 | registration is already deregistered                                                    |
| 100.150.203 | registration is not valid, probably initially rejected                                  |
| 100.150.204 | account registration reference pointed to no registration transaction                   |
| 100.150.205 | referenced registration does not contain an account                                     |
| 100.150.300 | payment only allowed with valid initial registration                                    |
| 100.350.100 | referenced session is REJECTED (no action possible).                                    |
| 100.350.101 | referenced session is CLOSED (no action possible)                                       |
| 100.350.200 | undefined session state                                                                 |
| 100.350.201 | referencing a registration through reference id is not applicable for this payment type |
| 100.350.301 | confirmation (CF) must be registered (RG) first                                         |
| 100.350.302 | session already confirmed (CF)                                                          |
| 100.350.303 | cannot deregister (DR) unregistered account and/or customer                             |
| 100.350.310 | cannot confirm (CF) session via XML                                                     |
| 100.350.311 | cannot confirm (CF) on a registration passthrough channel                               |
| 100.350.312 | cannot do passthrough on non-internal connector                                         |
| 100.350.313 | registration of this type has to provide confirmation url                               |
| 100.350.314 | customer could not be notified of pin to confirm registration (channel)                 |
| 100.350.315 | customer could not be notified of pin to confirm registration (sending failed)          |
| 100.350.400 | no or invalid PIN (email/SMS/MicroDeposit authentication) entered                       |
| 100.350.500 | unable to obtain personal (virtual) account - most likely no more accounts available    |
| 100.350.601 | registration is not allowed to reference another transaction                            |
| 100.350.602 | Registration is not allowed for recurring payment migration                             |

#### Result codes for rejections due to job validation

The regular expression pattern for filtering out this group is: `/^(100\.250|100\.360)/`

| Result Code | Result Description                                                        |
| ----------- | ------------------------------------------------------------------------- |
| 100.250.100 | job contains no execution information                                     |
| 100.250.105 | invalid or missing action type                                            |
| 100.250.106 | invalid or missing duration unit                                          |
| 100.250.107 | invalid or missing notice unit                                            |
| 100.250.110 | missing job execution                                                     |
| 100.250.111 | missing job expression                                                    |
| 100.250.120 | invalid execution parameters, combination does not conform to standard    |
| 100.250.121 | invalid execution parameters, hour must be between 0 and 23               |
| 100.250.122 | invalid execution parameters, minute and seconds must be between 0 and 59 |
| 100.250.123 | invalid execution parameters, Day of month must be between 1 and 31       |
| 100.250.124 | invalid execution parameters, month must be between 1 and 12              |
| 100.250.125 | invalid execution parameters, Day of week must be between 1 and 7         |
| 100.250.250 | Job tag missing                                                           |
| 100.360.201 | unknown schedule type                                                     |
| 100.360.300 | cannot schedule(SD) unscheduled job                                       |
| 100.360.303 | cannot deschedule(DS) unscheduled job                                     |
| 100.360.400 | schedule module not configured for LIVE transaction mode                  |

#### Result codes for rejections due to reference validation

The regular expression pattern for filtering out this group is: `/^(700\.[1345][05]0)/`

| Result Code | Result Description                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| 700.100.100 | reference id not existing                                                                                    |
| 700.100.200 | non matching reference amount                                                                                |
| 700.100.300 | invalid amount (probably too large)                                                                          |
| 700.100.400 | referenced payment method does not match with requested payment method                                       |
| 700.100.500 | referenced payment currency does not match with requested payment currency                                   |
| 700.100.600 | referenced mode does not match with requested payment mode                                                   |
| 700.100.700 | referenced transaction is of inappropriate type                                                              |
| 700.100.701 | referenced a DB transaction without explicitly providing an account. Not allowed to used referenced account. |
| 700.100.710 | cross-linkage of two transaction-trees                                                                       |
| 700.300.100 | referenced tx can not be refunded, captured or reversed (invalid type)                                       |
| 700.300.200 | referenced tx was rejected                                                                                   |
| 700.300.300 | referenced tx can not be refunded, captured or reversed (already refunded, captured or reversed)             |
| 700.300.400 | referenced tx can not be captured (cut off time reached)                                                     |
| 700.300.500 | chargeback error (multiple chargebacks)                                                                      |
| 700.300.600 | referenced tx can not be refunded or reversed (was chargebacked)                                             |
| 700.300.700 | referenced tx can not be reversed (reversal not possible anymore)                                            |
| 700.300.800 | referenced tx can not be voided                                                                              |
| 700.400.000 | serious workflow error (call support)                                                                        |
| 700.400.100 | cannot capture (PA value exceeded, PA reverted or invalid workflow?)                                         |
| 700.400.101 | cannot capture (Not supported by authorization system)                                                       |
| 700.400.200 | cannot refund (refund volume exceeded or tx reversed or invalid workflow?)                                   |
| 700.400.300 | cannot reverse (already refunded\|reversed, invalid workflow or amount exceeded)                             |
| 700.400.400 | cannot chargeback (already chargebacked or invalid workflow?)                                                |
| 700.400.402 | chargeback can only be generated internally by the payment system                                            |
| 700.400.410 | cannot reversal chargeback (chargeback is already reversaled or invalid workflow?)                           |
| 700.400.411 | cannot reverse chargeback or invalid workflow (second chargeback)                                            |
| 700.400.420 | cannot reversal chargeback (no chargeback existing or invalid workflow?)                                     |
| 700.400.510 | capture needs at least one successful transaction of type (PA)                                               |
| 700.400.520 | refund needs at least one successful transaction of type (CP or DB or RB or RC)                              |
| 700.400.530 | reversal needs at least one successful transaction of type (CP or DB or RB or PA)                            |
| 700.400.540 | reconceile needs at least one successful transaction of type (CP or DB or RB)                                |
| 700.400.550 | chargeback needs at least one successful transaction of type (CP or DB or RB)                                |
| 700.400.560 | receipt needs at least one successful transaction of type (PA or CP or DB or RB)                             |
| 700.400.561 | receipt on a registration needs a successfull registration in state 'OPEN'                                   |
| 700.400.562 | receipts can only be generated internally by the payment system                                              |
| 700.400.565 | finalize needs at least one successful transaction of type (PA or DB)                                        |
| 700.400.570 | cannot reference a waiting/pending transaction                                                               |
| 700.400.580 | cannot find transaction                                                                                      |
| 700.400.590 | installment needs at least one successful transaction of type (DB or PA)                                     |
| 700.400.600 | finalize needs at least one successful transaction of type (IN, DB, or PA)                                   |
| 700.400.700 | initial and referencing channel-ids do not match                                                             |
| 700.450.001 | cannot transfer money from one account to the same account                                                   |
| 700.500.001 | referenced session contains too many transactions                                                            |
| 700.500.002 | capture or preauthorization appears too late in referenced session                                           |
| 700.500.003 | test accounts not allowed in production                                                                      |
| 700.500.004 | cannot refer a transaction which contains deleted customer information                                       |

#### Result codes for rejections due to format validation

The regular expression pattern for filtering out this group is: `/^(200\.[123]|100\.[53][07]|800\.900|100\.[69]00\.500)/`

| Result Code | Result Description                                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| 100.300.101 | invalid test mode (please use LIVE or INTEGRATOR\_TEST or CONNECTOR\_TEST)                                                      |
| 100.300.200 | transaction id too long                                                                                                         |
| 100.300.300 | invalid reference id                                                                                                            |
| 100.300.400 | missing or invalid channel id                                                                                                   |
| 100.300.401 | missing or invalid sender id                                                                                                    |
| 100.300.402 | missing or invalid version                                                                                                      |
| 100.300.501 | invalid response id                                                                                                             |
| 100.300.600 | invalid or missing user login                                                                                                   |
| 100.300.601 | invalid or missing user pwd                                                                                                     |
| 100.300.700 | invalid relevance                                                                                                               |
| 100.300.701 | invalid relevance for given payment type                                                                                        |
| 100.370.100 | transaction declined                                                                                                            |
| 100.370.101 | responseUrl not set in Transaction/Frontend                                                                                     |
| 100.370.102 | malformed responseUrl in Transaction/Frontend                                                                                   |
| 100.370.110 | transaction must be executed for German address                                                                                 |
| 100.370.111 | system error( possible incorrect/missing input data)                                                                            |
| 100.370.121 | no or unknown ECI Type defined in Authentication                                                                                |
| 100.370.122 | parameter with null key provided in 3DSecure Authentication                                                                     |
| 100.370.123 | no or unknown verification type defined in 3DSecure Authentication                                                              |
| 100.370.124 | unknown parameter key in 3DSecure Authentication                                                                                |
| 100.370.125 | Invalid 3DSecure Verification\_ID. Must have Base64 encoding a Length of 28 digits                                              |
| 100.370.131 | no or unknown authentication type defined in Transaction/Authentication\@type                                                   |
| 100.370.132 | no result indicator defined Transaction/Authentication/resultIndicator                                                          |
| 100.500.101 | payment method invalid                                                                                                          |
| 100.500.201 | payment type invalid                                                                                                            |
| 100.500.301 | invalid due date                                                                                                                |
| 100.500.302 | invalid mandate date of signature                                                                                               |
| 100.500.303 | invalid mandate id                                                                                                              |
| 100.500.304 | invalid mandate external id                                                                                                     |
| 100.600.500 | usage field too long                                                                                                            |
| 100.900.500 | invalid recurrence mode                                                                                                         |
| 200.100.101 | invalid Request Message. No valid XML. XML must be url-encoded! maybe it contains a not encoded ampersand or something similar. |
| 200.100.102 | invalid Request. XML load missing (XML string must be sent within parameter 'load')                                             |
| 200.100.103 | invalid Request Message. The request contains structural errors                                                                 |
| 200.100.150 | transaction of multirequest not processed because of subsequent problems                                                        |
| 200.100.151 | multi-request is allowed with a maximum of 10 transactions only                                                                 |
| 200.100.199 | Wrong Web Interface / URL used. Please check out the Tech Quick Start Doc Chapter 3.                                            |
| 200.100.201 | invalid Request/Transaction tag (not present or \[partially] empty)                                                             |
| 200.100.300 | invalid Request/Transaction/Payment tag (no or invalid code specified)                                                          |
| 200.100.301 | invalid Request/Transaction/Payment tag (not present or \[partially] empty)                                                     |
| 200.100.302 | invalid Request/Transaction/Payment/Presentation tag (not present or \[partially] empty)                                        |
| 200.100.401 | invalid Request/Transaction/Account tag (not present or \[partially] empty)                                                     |
| 200.100.402 | invalid Request/Transaction/Account(Customer, Relevance) tag (one of Account/Customer/Relevance must be present)                |
| 200.100.403 | invalid Request/Transaction/Analysis tag (Criterions must have a name and value)                                                |
| 200.100.404 | invalid Request/Transaction/Account (must not be present)                                                                       |
| 200.100.501 | invalid or missing customer                                                                                                     |
| 200.100.502 | invalid Request/Transaction/Customer/Name tag (not present or \[partially] empty)                                               |
| 200.100.503 | invalid Request/Transaction/Customer/Contact tag (not present or \[partially] empty)                                            |
| 200.100.504 | invalid Request/Transaction/Customer/Address tag (not present or \[partially] empty)                                            |
| 200.100.601 | invalid Request/Transaction/(ApplePay\|GooglePay) tag (not present or \[partially] empty)                                       |
| 200.100.602 | invalid Request/Transaction/(ApplePay\|GooglePay)/PaymentToken tag (not present or \[partially] empty)                          |
| 200.100.603 | invalid Request/Transaction/(ApplePay\|GooglePay)/PaymentToken tag (decryption error)                                           |
| 200.200.106 | duplicate transaction. Please verify that the UUID is unique                                                                    |
| 200.300.403 | Invalid HTTP method                                                                                                             |
| 200.300.404 | invalid or missing parameter                                                                                                    |
| 200.300.405 | Duplicate entity                                                                                                                |
| 200.300.406 | Entity not found                                                                                                                |
| 200.300.407 | Entity not specific enough                                                                                                      |
| 800.900.100 | sender authorization failed                                                                                                     |
| 800.900.101 | invalid email address (probably invalid syntax)                                                                                 |
| 800.900.200 | invalid phone number (has to start with a digit or a '+', at least 7 and max 25 chars long)                                     |
| 800.900.201 | unknown channel                                                                                                                 |
| 800.900.300 | invalid authentication information                                                                                              |
| 800.900.301 | user authorization failed, user has no sufficient rights to process transaction                                                 |
| 800.900.302 | Authorization failed                                                                                                            |
| 800.900.303 | No token created                                                                                                                |
| 800.900.399 | Secure Registration Problem                                                                                                     |
| 800.900.401 | Invalid IP number                                                                                                               |
| 800.900.450 | Invalid birthdate                                                                                                               |

#### Result codes for rejections due to address validation

The regular expression pattern for filtering out this group is: `/^(100\.800)/`

| Result Code | Result Description                                                     |
| ----------- | ---------------------------------------------------------------------- |
| 100.800.100 | request contains no street                                             |
| 100.800.101 | The combination of street1 and street2 must not exceed 201 characters. |
| 100.800.102 | The combination of street1 and street2 must not contain only numbers.  |
| 100.800.200 | request contains no zip                                                |
| 100.800.201 | zip too long                                                           |
| 100.800.202 | invalid zip                                                            |
| 100.800.300 | request contains no city                                               |
| 100.800.301 | city too long                                                          |
| 100.800.302 | invalid city                                                           |
| 100.800.400 | invalid state/country combination                                      |
| 100.800.401 | state too long                                                         |
| 100.800.500 | request contains no country                                            |
| 100.800.501 | invalid country                                                        |

#### Result codes for rejections due to contact validation

The regular expression pattern for filtering out this group is: `/^(100\.[97]00)/`

| Result Code | Result Description                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------------- |
| 100.700.100 | customer.surname may not be null                                                                   |
| 100.700.101 | customer.surname length must be between 0 and 50                                                   |
| 100.700.200 | customer.givenName may not be null                                                                 |
| 100.700.201 | customer.givenName length must be between 0 and 50                                                 |
| 100.700.300 | invalid salutation                                                                                 |
| 100.700.400 | invalid title                                                                                      |
| 100.700.500 | company name too long                                                                              |
| 100.700.800 | identity contains no or invalid 'paper'                                                            |
| 100.700.801 | identity contains no or invalid identification value                                               |
| 100.700.802 | identification value too long                                                                      |
| 100.700.810 | specify at least one identity                                                                      |
| 100.900.100 | request contains no email address                                                                  |
| 100.900.101 | invalid email address (probably invalid syntax)                                                    |
| 100.900.105 | email address too long (max 50 chars)                                                              |
| 100.900.200 | invalid phone number (has to start with a digit or a '+', at least 7 and max 25 chars long)        |
| 100.900.300 | invalid mobile phone number (has to start with a digit or a '+', at least 7 and max 25 chars long) |
| 100.900.301 | mobile phone number mandatory                                                                      |
| 100.900.400 | request contains no ip number                                                                      |
| 100.900.401 | invalid ip number                                                                                  |
| 100.900.450 | invalid birthdate                                                                                  |
| 100.900.500 | invalid recurrence mode                                                                            |

#### Result codes for rejections due to account validation

The regular expression pattern for filtering out this group is: `/^(100\.100|100.2[01])/`

| Result Code | Result Description                                                                                        |
| ----------- | --------------------------------------------------------------------------------------------------------- |
| 100.100.100 | request contains no creditcard, bank account number or bank name                                          |
| 100.100.101 | invalid creditcard, bank account number or bank name                                                      |
| 100.100.104 | invalid unique id / root unique id                                                                        |
| 100.100.200 | request contains no month                                                                                 |
| 100.100.201 | invalid month                                                                                             |
| 100.100.300 | request contains no year                                                                                  |
| 100.100.301 | invalid year                                                                                              |
| 100.100.303 | card expired                                                                                              |
| 100.100.304 | card not yet valid                                                                                        |
| 100.100.305 | invalid expiration date format                                                                            |
| 100.100.400 | request contains no cc/bank account holder                                                                |
| 100.100.401 | cc/bank account holder too short or too long                                                              |
| 100.100.402 | cc/bank account holder not valid                                                                          |
| 100.100.500 | request contains no credit card brand                                                                     |
| 100.100.501 | invalid credit card brand                                                                                 |
| 100.100.600 | empty CVV for VISA,MASTER, AMEX not allowed                                                               |
| 100.100.601 | invalid CVV/brand combination                                                                             |
| 100.100.650 | empty CreditCardIssueNumber for MAESTRO not allowed                                                       |
| 100.100.651 | invalid CreditCardIssueNumber                                                                             |
| 100.100.700 | invalid cc number/brand combination                                                                       |
| 100.100.701 | suspecting fraud, this card may not be processed                                                          |
| 100.200.100 | bank account contains no or invalid country                                                               |
| 100.200.103 | bank account has invalid bankcode/name account number combination                                         |
| 100.200.104 | bank account has invalid acccount number format                                                           |
| 100.200.200 | bank account needs to be registered and confirmed first. Country is mandate based.                        |
| 100.210.101 | virtual account contains no or invalid Id                                                                 |
| 100.210.102 | virtual account contains no or invalid brand                                                              |
| 100.211.101 | user account contains no or invalid Id                                                                    |
| 100.211.102 | user account contains no or invalid brand                                                                 |
| 100.211.103 | no password defined for user account                                                                      |
| 100.211.104 | password does not meet safety requirements (needs 8 digits at least and must contain letters and numbers) |
| 100.211.105 | wallet id has to be a valid email address                                                                 |
| 100.211.106 | voucher ids have 32 digits always                                                                         |
| 100.212.101 | wallet account registration must not have an initial balance                                              |
| 100.212.102 | wallet account contains no or invalid brand                                                               |
| 100.212.103 | wallet account payment transaction needs to reference a registration                                      |

#### Result codes for rejections due to amount validation

The regular expression pattern for filtering out this group is: `/^(100\.55)/`

| Result Code | Result Description                                                          |
| ----------- | --------------------------------------------------------------------------- |
| 100.550.300 | request contains no amount or too low amount                                |
| 100.550.301 | amount too large                                                            |
| 100.550.303 | amount format invalid (only two decimals allowed).                          |
| 100.550.310 | amount exceeds limit for the registered account.                            |
| 100.550.311 | exceeding account balance                                                   |
| 100.550.312 | Amount is outside allowed ticket size boundaries                            |
| 100.550.400 | request contains no currency                                                |
| 100.550.401 | invalid currency                                                            |
| 100.550.601 | risk amount too large                                                       |
| 100.550.603 | risk amount format invalid (only two decimals allowed)                      |
| 100.550.605 | risk amount is smaller than amount (it must be equal or bigger then amount) |
| 100.550.701 | amounts not matched                                                         |
| 100.550.702 | currencies not matched                                                      |

#### Result codes for rejections due to risk management

The regular expression pattern for filtering out this group is: `/^(100\.380\.[23]|100\.380\.101)/`

| Result Code | Result Description                                             |
| ----------- | -------------------------------------------------------------- |
| 100.380.101 | transaction contains no risk management part                   |
| 100.380.201 | no risk management process type specified                      |
| 100.380.305 | no frontend information provided for asynchronous transaction  |
| 100.380.306 | no authentication data provided in risk management transaction |

### Chargeback related result codes

The regular expression pattern for filtering out this group is: `/^(000\.100\.2)/`

| Result Code | Result Description                                                                        |
| ----------- | ----------------------------------------------------------------------------------------- |
| 000.100.200 | Reason not Specified                                                                      |
| 000.100.201 | Account or Bank Details Incorrect                                                         |
| 000.100.202 | Account Closed                                                                            |
| 000.100.203 | Insufficient Funds                                                                        |
| 000.100.204 | Mandate not Valid                                                                         |
| 000.100.205 | Mandate Cancelled                                                                         |
| 000.100.206 | Revocation or Dispute                                                                     |
| 000.100.207 | Cancellation in Clearing Network                                                          |
| 000.100.208 | Account Blocked                                                                           |
| 000.100.209 | Account does not exist                                                                    |
| 000.100.210 | Invalid Amount                                                                            |
| 000.100.211 | Transaction succeeded (amount of transaction is smaller then amount of pre-authorization) |
| 000.100.212 | Transaction succeeded (amount of transaction is greater then amount of pre-authorization) |
| 000.100.220 | Fraudulent Transaction                                                                    |
| 000.100.221 | Merchandise Not Received                                                                  |
| 000.100.222 | Transaction Not Recognized By Cardholder                                                  |
| 000.100.223 | Service Not Rendered                                                                      |
| 000.100.224 | Duplicate Processing                                                                      |
| 000.100.225 | Credit Not Processed                                                                      |
| 000.100.226 | Cannot be settled                                                                         |
| 000.100.227 | Configuration Issue                                                                       |
| 000.100.228 | Temporary Communication Error - Retry                                                     |
| 000.100.229 | Incorrect Instructions                                                                    |
| 000.100.230 | Unauthorised Charge                                                                       |
| 000.100.299 | Unspecified (Technical)                                                                   |


# Plugins

&#x20;We have a list of plugins recognized by us, but they are third-party plugins and we cannot give support.

[**https://docs.aciworldwide.com/tutorials/plugins**](https://docs.aciworldwide.com/tutorials/plugins)


# Tokenization & Registration

{% hint style="info" %}
NOTE: You should be fully PCI compliant if you wish to perform tokenization requests server-to-server (as it requires that you collect the card data). If you are not fully PCI compliant, you can use the [PrimeiroPay tokenization tutorial ](https://developers.primeiropay.com/tokenization)to collect the payment data securely.
{% endhint %}

Tokenization allows you to store the payment data for later use. This can be useful for recurring and/or one-click payment scenarios.

This guide describes how you can store the data using our Server-to-Server API, how you can subsequently use the stored card details for a one-click payment and how to delete stored data.

### Storing the payment data

There are two methods for creating a token

* Store the data [during a payment](https://developers.primeiropay.com/tokenization-and-registration#store-the-data-during-a-payment)
* Store the data as [stand-alone](https://developers.primeiropay.com/tokenization-and-registration#store-the-data-as-stand-alone)

#### Store the data during a payment

A payment's data can be stored at the same time as the payment by sending the `createRegistration` parameter with a value of `true`. This is done by sending a POST request to the /payments endpoint.

Try it out in the interactive editor below and you will find that you get the additional response parameter `registrationId`. This parameter allows you to access the stored payment data during subsequent operations (see use cases below).st.oppwa.com/v1/payments \\

```
 -d "entityId=8a8294184e736012014e78a17a5615ac" \
 -d "amount=92.00" \
 -d "currency=EUR" \
 -d "paymentBrand=VISA" \
 -d "paymentType=DB" \
 -d "card.number=4200000000000000" \
 -d "card.holder=Jane Jones" \
 -d "card.expiryMonth=05" \
 -d "card.expiryYear=2034" \
 -d "card.cvv=123" \
 -d "createRegistration=true" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

#### Store the data as stand-alone

A registration can also be made by calling the `/registrations` endpoint as a stand-alone request (i.e. without requesting a payment).

Contrary to the registration as part of a payment, you directly receive a registration object in your response. Therefore the ID to reference this data during later payments is the value of field `id`

```
curl https://test.oppwa.com/v1/registrations \
 -d "entityId=8a8294184e736012014e78a17a5615ac" \
 -d "paymentBrand=VISA" \
 -d "card.number=4200000000000000" \
 -d "card.holder=Jane Jones" \
 -d "card.expiryMonth=05" \
 -d "card.expiryYear=2034" \
 -d "card.cvv=123" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```

Try it Out

* **Using the stored payment data**

  **Use Case 1: Recurring Payments**

  Based on the stored account details recurring payments become very simple to achieve.

  All you need to do is to add the parameter `recurringType` to your requests:

  * For the initial payment request you should send the `recurringType` with value `INITIAL`.
  * For any subsequent payment you should send the `recurringType` with value `REPEATED`.

  &#x20;The [Recurring Payment tutorial](https://developers.primeiropay.com/getting-started/server-to-server-api/recurring-1) explains this scenario in more detail.
* **Use Case 2: One-Click Payments**

  After storing a customer's account details, it is possible to offer a 'one-click payment' checkout, to simplify subsequent purchases.

  Basically you're using the token you've received in the original payment's response in the field `registrationId/id` to reference and even prefill a customer's payment form.

  ![one-click checkout ](https://primeiropay.docs.oppwa.com/sites/default/files/one-click-checkout-mini.png)

  The [One-click Payment tutorial ](https://primeiropay.docs.oppwa.com/one-click-payment-guide)explains this scenario in more detail.

### Deleting the stored payment data

Once stored, a token can be deleted using the HTTP `DELETE` method against the `registration.id`:

```
https://test.oppwa.com/v1/registrations/
```

```
curl -X DELETE "https://test.oppwa.com/v1/registrations/{id}\
?entityId=8a8294184e736012014e78a17a5615ac" \
 -H "Authorization: Bearer OGE4Mjk0MTg0ZTczNjAxMjAxNGU3OGExN2E2YTE1YjB8ZjJGRUtacXRCUA=="
```


# Tokenization

Tokenization allows you to store payment data for later use. This can be useful for recurring and/or one-click payment scenarios.

This guide will describe how you can store account details using Primeiro Pay and how you can subsequently use the stored account details.

### Storing the payment data

PrimeiroPay provides two options for storing the payment data:

* [Store the data during a payment](https://developers.primeiropay.com/tokenization#store-the-data-during-a-payment): When a shopper is checking out for the first time, he has to fill in his complete payment- and address data. Use this option to automatically store his data during the payment for reuse in later transactions.
* [Store the data as stand-alone](https://developers.primeiropay.com/tokenization#store-the-data-as-stand-alone): If your site provides shoppers with an administrative area where they can register their payment details independent of a checkout-process, this option is for you.

#### Store the data during a payment

You have two options for achieving this:

* [Merchant-determined](https://developers.primeiropay.com/tokenization#merchant-determined-tokenization) tokenization
* [Shopper-determined](https://developers.primeiropay.com/tokenization#shopper-determined-tokenization) tokenization.

#### **Merchant-determined tokenization**

During the checkout process you can store the data by adding an additional parameter to the normal prepare checkout request as described in [step 1 of the Primeiro Pay checkout](https://primeiropay.docs.oppwa.com/integration-guide#CNPStep1):

```
createRegistration=true
```

After the account holder has filled in their account information and are redirected back to your `shopperResultUrl`, you can retrieve the response information as usual ([step 3](https://primeiropay.docs.oppwa.com/integration-guide#CNPStep3)). This time, however, the response will include a `registrationId` (token) and useful card information that you can store for future 'one-click payment' requests.

#### **Shopper-determined tokenization**

When the payment form is displayed as described in [step 2 of the Primeiro Pay checkout](https://primeiropay.docs.oppwa.com/integration-guide#CNPStep2), you can extend the form to display an option to your customer that allows him store his account data.

This can be achieved very easily by using the [Primeiro Pay API](https://primeiropay.docs.oppwa.com/widget-api). You can see an example implementation of this in the "store payment details" use case that is part of the[ Advanced Options](https://developers.primeiropay.com/getting-started/hosted-checkout/copy-and-pay-1/advanced-options) tutorial.

[![](https://primeiropay.docs.oppwa.com/sites/default/files/tokenizationCNPForm.png)](https://primeiropay.docs.oppwa.com/advanced-options)

After the account holder has filled in his account information and was redirected to the  `shopperResultUrl`, you can retrieve the response information as usual ([step 3](https://primeiropay.docs.oppwa.com/integration-guide#CNPStep3)). This time, however, the response will include a `registrationId` (token) and useful card information that you can store for future 'one-click payment' requests.

#### Store the data as stand-alone

With Primeiro Pay it is also possible to create a just registration separate from any later payment.

A registration-only transaction with Primeiro Pay is basically using the same workflow and parameters as a payment.

You only have to change two parameters in [**step1**](https://primeiropay.docs.oppwa.com/integration-guide#CNPStep1):

* `createRegistration=true` has to be sent.
* `paymentType` should not be sent.

Now Primeiro Pay **automatically adapts the workflow** for handling a registration:

* In [step2](https://primeiropay.docs.oppwa.com/integration-guide#CNPStep2) Primeiro Pay will render the payment form as usual, but send the form to `https://{test.}oppwa.com/v1/checkouts/{checkoutId}/`**`registration`**
* In [step3](https://primeiropay.docs.oppwa.com/integration-guide#CNPStep3) you'll get back a resourcePath pointing to you to query for a registration's result: `resourcePath=/v1/checkouts/{checkoutId}/`**`registration`**

IMPORTANT: The baseUrl (that is prepended to the resourcePath) must end in a "/", e.g. "<https://test.oppwa.com/>".

### Using the payment data

#### Use Case 1: Recurring Payment

Based on the stored account details, recurring payments become very simple to achieve.

All you need to do is to add the parameter `recurringType` to your request to the /checkouts endpoint (see [step1](https://primeiropay.docs.oppwa.com/integration-guide#CNPStep1)):

* For the initial payment request you should send the `recurringType` with value `INITIAL`.
* For any subsequent payment you should send the `recurringType` with value `REPEATED`.

The [Recurring Payment tutorial](https://developers.primeiropay.com/getting-started/server-to-server-api/recurring-1) explains this scenario in more detail.

#### Use Case 2: One-Click Payment

After storing a customer's account details, it is possible to offer a 'one-click payment' checkout, to simplify subsequent purchases.

Basically you're using the token you've received in the original payment's response in the field `registrationId` to reference and even prefill a customer's payment form.

![one-click checkout ](https://primeiropay.docs.oppwa.com/sites/default/files/one-click-checkout-mini.png)

The Server-to-Server [One-click Payment tutorial](https://primeiropay.docs.oppwa.com/tutorials/integration-guide/one-click)

Or

Primeiro Pay [One-click Checkout tutorial](https://primeiropay.docs.oppwa.com/tutorials/integration-guide/one-click) explains this scenario in more detail.