# Overview

The API parameters are organized into distinct objects to streamline the payment process and ensure clarity in data handling. Each object represents a specific aspect of the transaction, making it easier to manage and understand the flow of information. However, some parameters stand alone and are not part of any object. Below is an overview of the objects and their corresponding parameters, as well as the standalone parameters:

* **Customer**: Represents the individual making the payment. This object includes critical information about the customer, such as their unique ID, name, email address, and optionally, their IP address and birthdate. The **customer.document** sub-object details the type and number of the customer's official identification, while the **customer.address** sub-object includes the customer's full address, which may be required depending on the payment method.
* **Transaction**: This object contains all the essential details about the transaction itself, including a unique transaction ID, the currency used, the total amount involved, and optionally, the time until the transaction expires.
* **Payment**: Represents the payment method and related URLs for completing the transaction. This object is crucial for determining how the customer will pay and where they will be redirected after the payment is completed.
* **Values**: This object provides detailed financial information related to the transaction. It includes the original and converted amounts, the currencies involved, the exchange rate applied, and any fees associated with the transaction.

Standalone parameters, such as **branch**, **country**, **notification\_url**, and **redirect\_url**, do not belong to any specific object. These parameters provide additional information relevant to the transaction, such as the location of the transaction, the country code, where payment notifications should be sent, and where the customer should be redirected after completing the payment.

Our API structure remains consistent across different payment methods and countries, making it easy to adapt as you expand into new regions or integrate new methods.

{% hint style="info" %}
**Knowing the parameters used**
{% endhint %}

<table><thead><tr><th width="346">Parameter</th><th width="120" align="center">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>customer.id</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>Unique identifier for the customer in your system. This value should remain consistent across all transactions for the same customer</td></tr><tr><td><code>customer.name</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The full name of the customer making the payment. It should match the name on the customer's identification documents</td></tr><tr><td><code>customer.email</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The email address of the customer. This will be used for sending payment confirmations and notifications</td></tr><tr><td><code>customer.phone</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The phone number of the customer, including the country code. This parameter may be optional or required depending on the payment method used</td></tr><tr><td><code>customer.birthdate</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The birthdate of the customer, provided in the format <code>mm-dd-yyyy</code>. This parameter may be required depending on the country regulations or the payment method</td></tr><tr><td><code>customer.document.number</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The official identification number of the customer. This is typically a national ID, or other government-issued document</td></tr><tr><td><code>customer.document.type</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The type of document provided by the customer. Common types include national ID, or driver's license. <a href="../../thesmartway/api-requests/document-type">List of documents allowed</a>.</td></tr><tr><td><code>customer.address.addres_1</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The primary street address of the customer </td></tr><tr><td><code>customer.address.addres_2</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>Additional address information, such as apartment number or suite</td></tr><tr><td><code>customer.address.city</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The city in which the customer resides</td></tr><tr><td><code>customer.address.country_code</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The ISO 3166-1 alpha-3 country code for the customer's address. <a href="../../thesmartway/api-requests/country-codes">List of country codes.</a></td></tr><tr><td><code>customer.address.neightborhood</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The neighborhood or district of the customer's address</td></tr><tr><td><code>customer.address.number</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The street number of the address</td></tr><tr><td><code>customer.address.postal_code</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The postal or ZIP code for the customer's address</td></tr><tr><td><code>customer.address.state</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The state or region of the customer's address </td></tr><tr><td><code>transaction.id</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>A unique identifier for the transaction. This ID should be generated by your system to track the specific payment process</td></tr><tr><td><code>transaction.currency</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The currency in which the transaction is being conducted. Use standard ISO 4217 currency codes (e.g., USD, PEN). <a href="../../thesmartway/api-requests/currency-codes">List of currency codes</a>.</td></tr><tr><td><code>transaction.amount</code></td><td align="center"><mark style="color:red;"><code>decimal</code></mark><br><mark style="color:red;"><code>(10,2)</code></mark></td><td>The total amount of the transaction in the specified currency. This value should be a numeric amount (use dot instead of comma)<br><mark style="color:red;"><code>Eg: 300.10</code></mark></td></tr><tr><td><code>transaction.expire</code></td><td align="center"><mark style="color:red;"><code>integer (11)</code></mark></td><td>The time in seconds until the transaction expires and is no longer valid</td></tr><tr><td><code>branch</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The specific branch or location identifier where the transaction is being processed, if applicable</td></tr><tr><td><code>country</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The country code where the transaction is taking place. The format is <code>ISO 3166-1 alpha-3</code> (e.g., BRA for Brazil). <a href="../../thesmartway/api-requests/country-codes">List of country codes.</a></td></tr><tr><td><code>payment_method</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The method of payment being used for the transaction, such as bank transfer, credit card...</td></tr><tr><td><code>notification_url</code></td><td align="center"><mark style="color:red;"><code>string</code></mark></td><td>The URL to which payment notifications will be sent. Ensure this URL is accessible and configured to handle the notification format</td></tr></tbody></table>

{% hint style="info" %}
**Example response payment method request**
{% endhint %}

{% tabs %}
{% tab title="success" %}

```json
{
    "requestId": "a2435636-5f69-447d-8e22-8382f62ef7dd",
    "data": {
        "id": "4a79f3b4-8d55-428b-a560-984fedd6f78a",
        "status": "pending",
        "expires_in": 1722108649,
        "payment": {
            "method": "picpay",
            "qr_code": "00...014COM.PICPAY.P2B0164https:\\app.picpay.com\checkout\SMARTFASTPAY...AY6009SAO PAULXXXXX",
            "url": "https:\\app.picpay.com\checkout\SMARTFASTPAY",
            "name": "Viacredi", // only payment method is bank_transfer
            "code": "085", // only payment method is bank_transfer
            "agency": "0101-5", // only payment method is bank_transfer
            "account": "12551163", // only payment method is bank_transfer
            "account_operation": "Conta Corrente", // only payment method is bank_transfer
            "document": "34.911.051/0001-97", // only payment method is bank_transfer
            "beneficiary": "SmartFastPay" // only payment method is bank_transfer
        },
        "values": {
            "source_total": 27525.47,
            "source_currency": "BRL",
            "exchanged_total": 27525.47,
            "exchanged_currency": "BRL",
            "exchange": 1.00,
            "fee": 92.5226
        }
    }
}
```

{% endtab %}

{% tab title="error" %}

```json
{
    "requestId": "b299549a8e75ead38c176932c3f59da0/13462186452875824120",
    "moreInformation": [
        {
            "code": "INVALID_REQUEST",
            "detail": "The transaction.id field is required."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Response details**
{% endhint %}

<table><thead><tr><th width="296">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>A unique identifier for the response generated by the payment system, used to track the transaction. Can be used to verify the payment status in the<br> <a href="../../../api-reference/payments#get-payment-id"><mark style="color:green;"><strong>GET</strong> /payment/{id}</mark></a> endpoint</td></tr><tr><td><code>status</code></td><td>The current status of the transaction such as <mark style="color:red;"><code>pending</code></mark>, <mark style="color:red;"><code>paid</code></mark>, <mark style="color:red;"><code>denied</code></mark>, <mark style="color:red;"><code>expired</code></mark></td></tr><tr><td><code>expires_in</code></td><td>The time in seconds until the transaction expires and is no longer valid</td></tr><tr><td><code>payment.method</code></td><td>The payment method that was used for the transaction, such as <mark style="color:red;"><code>bank_transfer</code></mark>, <mark style="color:red;"><code>credit_card</code></mark>, <mark style="color:red;"><code>picpay</code></mark>...</td></tr><tr><td><code>payment.url</code></td><td>The URL provided to the customer for completing the payment. This might be a redirect to a bank or payment gateway</td></tr><tr><td><code>payment.qr_code</code></td><td>The string that contains the information of the qrcode. It is necessary to use some programming resource to convert this text into an image</td></tr><tr><td></td><td></td></tr><tr><td>bank info</td><td><mark style="color:red;">only bank_transfer</mark></td></tr><tr><td><code>payment.name</code></td><td>Name of the bank where the deposit is going to be made</td></tr><tr><td><code>payment.code</code></td><td>Brazilian code of the bank to which the deposit is going to be directed</td></tr><tr><td><code>payment.agency</code></td><td>Agency number with verification digit to which the deposit is going to be directed</td></tr><tr><td><code>payment.account</code></td><td>Account number with verification digit to which the deposit is going to be directed</td></tr><tr><td><code>payment.account_operation</code></td><td>Either it's a savings account or a current account. <mark style="color:red;"><code>current account</code></mark>, <mark style="color:red;"><code>saving account</code></mark></td></tr><tr><td><code>payment.document</code></td><td>Either the owner document or the company document for the account to which the deposit is going to be directed</td></tr><tr><td><code>payment.beneficiary</code></td><td>Name of the owner of the account to which the deposit is going to be direct</td></tr><tr><td></td><td></td></tr><tr><td><code>values.source_total</code></td><td>The total amount of the transaction in the source currency before any exchange</td></tr><tr><td><code>values.source_currency</code></td><td>The original currency of the transaction as specified in the request</td></tr><tr><td><code>values.exchanged_total</code></td><td>The total amount of the transaction after currency conversion, if applicable</td></tr><tr><td><code>values.exchanged_currency</code></td><td>The currency in which the payment was completed after conversion</td></tr><tr><td><code>values.exchange</code></td><td>The exchange rate applied to convert the source currency to the target currency</td></tr><tr><td><code>values.fee</code></td><td>The amount charged by our service for processing the transaction</td></tr></tbody></table>

> **Note:**
>
> The **`payment.qr_code`** parameter can be provided in different formats depending on the scenario. **You might receive both a URL and a QR code, or just one of them**. In the example below, the payment method "picpay" includes both a QR code and a URL. Depending on the implementation, you may only need to use one of these elements, or both, to facilitate the payment process.

```json
"payment": {
    "method": "picpay",
    "qr_code": "00...014COM.PICPAY.P2B0164https:\\app.picpay.com\checkout\SMARTFASTPAY...AY6009SAO PAULXXXXX",
    "url": "https:\\app.picpay.com\checkout\SMARTFASTPAY"
},
```

***

Our API is **designed to be flexible and adaptable**, so as you expand into new regions or add more payment methods, you can easily apply these principles across different implementations.

If you need further details on other payment methods or countries, be sure to explore the rest of our documentation. Additionally, we have a **dedicated FAQ and support section** to help with common questions:

{% content-ref url="../../resources/faq-and-support" %}
[faq-and-support](https://docs.smartfastpay.com/resources/faq-and-support)
{% endcontent-ref %}