### Example Private Key (.key) Format

Source: https://docs.cielo.com.br/atendimento/docs/como-configurar-o-boleto-registrado-ita%C3%BA-api

This is an example of a private key file, typically with a .key extension. It contains the essential private key information required for secure communication and will be sent as 'Credencials.PrivateKey' during the onboarding process. Ensure this file is stored securely.

```text
-----BEGIN PRIVATE KEY-----
BEEGvwIBADANBgkqhkiG8w0BAQEFAASCBKkwggSlAgEAAoIBAQDFSQxt2LHLQhqI
1A/JJ2uBV+R4bKcM9RDi4T0S+EW4rYkmedgSnsfmuLQ8WlsWAH0O0cSlr5ozoFdU
Io97C/wD0zuNtmC/ekQeKItoef5/fVkePSbpwPZIQPGCEmDY8M/wkeI7zok6xF1B
BB1S3tqj/0Snkhtojnp6Eqdg2yZRTT6E2APVGoTt3rm7583ynAiqhbeBLbYm9jI4
Uq5PzOjs03MwS6J7P5lKWB1LsIt9dHAMAcGkcg2P3/sBk3qcOw80ZL5oI1h6mU3v
JZRS1w8UF/se95iByDl75d/utrHJeYpxNDGg0UZz7Fwpjr71IMBLHS36Po4jXqJ2
9EyM8gtlAgMBAAECggEAFaLuyYdH7H5J8bKsLofzuuI8TNbBtWKVIQTJ0XBIGTpy
/bTENTqTuuKL5ciVD8Mq8/qegftRwpK1sST/LmQAlhzO/bpAPw+2M8aHj4Q9nJbP
NMlJIL7IY+E3e2fvlitG6t/c+2kp1LefcJd2bdXCDdVbnrMf7WYe2Y99KtquB6Fr
KVXJL95I3rH5Ty7ts2cQ+ZgladSxYWaIvlfDhP7WjHunhN3c9q9lL8l1UIw4sK/L
MoEVj7Yu6HHgmAni6C/1iPuYK5l6h20n85geKqJdInpy0U24xFxV2Q/Xnx9PxInp
dL1wWdzZdcGyGTSnIWBvJcurB/8AfrBw3OztuVDKCwKBgQDyCdJ/tuTpNW7zczKZ
GyMrmrbD4HfoO6cJ0x0/zwRZ4i/sdVnAH9/9bf4rBWVPIzve/nfmHs1tw0IdQh08
PYxBDdVoglXCIFcLlTvFpc7xz4nxgLW6aBOElAyjz2WTtI6ZvaeJyu8vGnbXj5Fw
4lAUrD0MF9OrKJFmmqEK8ZWhPwKBgQDQqlvjMXGdd2eixJOfk0FbsZQKTI9v2a6A
G4ispWvGHMdSWqhOAj74VbZjQLNfXhqUtfseVGk+6ljWnA8UbYEix5TeW9oDYXuJ
SsqPxEDOwT+UaQIFWQw6nfQaBRrXLD2gTrhoiFrSmqaxZNbhMK1CcpeDwVPp6xQz
GoC3cDXGWwKBgQCKC+YeZ69J/+rnOaX7Q0oc/aIOOEHLl/JenSWKlkVSCrrwr8Hf
3Y5AmnKkEPDGYT8toY+7FYhveTWFQIcyK5yKIhy8/dFx5kYfWh98TGSq8Icp0hJU
XjX7oQFQkOLLiujmcRBUfAVNpVdw/PakHsAz+kTbV9+nOH0tuzXs6vs/uwKBgQCG
KiMurynYD2ApPa+VWL8bT9BZ1uQbDKGwaQO1zh6/oN1fzD6O+c63KZU9t+odFYqN
t3yhAbEx7Mf2JR1lCwuO6ziCyBgjOFiP6/DWA1+QEJzqtaHBAoJkZg7/c+zQEPgG
zNaxD4smAp3PTYEEBZ+FnVxiMLndm3K/cPj1+UX6JQKBgQDGO+AZusE6MimOlTQp
eyBF7o8fYRbk/fhbkEZX0oXZudVH2Su4qVfnvWU849JyMaJI1GiLmrMmTpjsOXLG
daNcC1oYlbXOr6jLtzo/In5YJzEXtUSSAV5OD3Wx0gG7BXynt+iumYIXayCvgbPQ
MyORpzbex1QxU9QgCDOPf+tMAt==
-----END PRIVATE KEY-----
```

--------------------------------

### Step 2: Obtaining Installment Options

Source: https://docs.cielo.com.br/gateway/docs/koin

Information on how to query Koin's API to get available payment installment plans.

```APIDOC
## Step 2: Obtaining Installment Options

### Description
This step involves querying the Koin API to retrieve available payment installment options that can be presented to the buyer in the checkout.

### Endpoint
POST /consult/installments

### Request Body
(Details of the request body parameters would go here, e.g., amount, currency, etc.)

### Response
#### Success Response (200)
- **Options** (array) - A list of available installment options.
  - **Id** (string) - Unique identifier for the installment option.
  - **NumberOfInstallments** (integer) - The number of installments.
  - **InstallmentValue** (decimal) - The value of each installment.
  - **FirstDueDate** (date) - The due date of the first installment.
  - **Fees** (decimal) - Any applicable fees.

### Request Example
(An example JSON request body would go here)

### Response Example
```json
{
  "Options": [
    {
      "Id": "option_123",
      "NumberOfInstallments": 3,
      "InstallmentValue": 100.50,
      "FirstDueDate": "2023-10-26",
      "Fees": 5.00
    },
    {
      "Id": "option_456",
      "NumberOfInstallments": 6,
      "InstallmentValue": 55.25,
      "FirstDueDate": "2023-11-01",
      "Fees": 10.00
    }
  ]
}
```

#### Note
If any details of the purchase are altered by the buyer, a new installment query is required.
```

--------------------------------

### Seller Onboarding API

Source: https://docs.cielo.com.br/split/reference/split-pelo-gateway-de-pagamentos

Register and query sellers, update fees in bulk, update bank details, and enable Pix payments.

```APIDOC
## POST /v1/sellers

### Description
Registers a new seller in the platform.

### Method
POST

### Endpoint
`https://splitonboardingapisandbox.braspag.com.br/v1/sellers`

### Parameters
#### Request Body
- **Name** (string) - Required - The name of the seller.
- **Document** (string) - Required - The seller's identification document number.
- **Email** (string) - Required - The seller's email address.
- **BankAccount** (object) - Required - Seller's bank account details.
  - **BankCode** (string) - Required - The bank code.
  - **BranchNumber** (string) - Required - The branch number.
  - **AccountNumber** (string) - Required - The account number.
  - **AccountType** (string) - Required - The type of account (e.g., 'Checking', 'Savings').
  - **Document** (string) - Required - The account holder's document number.
  - **Name** (string) - Required - The account holder's name.

### Request Example
```json
{
  "Name": "Seller Example Corp",
  "Document": "11222333000199",
  "Email": "seller@example.com",
  "BankAccount": {
    "BankCode": "001",
    "BranchNumber": "0001",
    "AccountNumber": "123456",
    "AccountType": "Checking",
    "Document": "11222333000199",
    "Name": "Seller Example Corp"
  }
}
```

### Response
#### Success Response (201)
- **SellerId** (string) - The unique identifier for the newly created seller.
- **Status** (string) - The status of the seller onboarding (e.g., 'Pending').

#### Response Example
```json
{
  "SellerId": "seller-abc-123",
  "Status": "Pending"
}
```
```

--------------------------------

### Cielo API: Installment Payment with Boleto Discount Example

Source: https://docs.cielo.com.br/link/reference/criar-p%C3%A1gina-checkout-api

An example JSON request illustrating a payment scenario with installments and a boleto discount. It includes order details, cart items, shipping information, and specific payment fields for `BoletoDiscount` and `Installments`.

```json
{
  "OrderNumber": "Pedido0123",
  "SoftDescriptor": "Nomefantasia",
  "Cart": {
    "Items": [
      {
        "Name": "Produto01",
        "Description": "ProdutoExemplo01",
        "UnitPrice": 100,
        "Quantity": 1,
        "Type": "Asset",
        "Sku": "ABC001",
        "Weight": 500
      }
    ]
  },
  "Shipping": {
    "SourceZipCode": "20020080",
    "TargetZipCode": "21911130",
    "Type": "FixedAmount",
    "Services": [
      {
        "Name": "Moto entrega",
        "Price": 1000,
        "Deadline": 15,
        "Carrier": null
      },
      {
        "Name": "Entrega Express",
        "Price": 1000,
        "Deadline": 2,
        "Carrier": null
      }
    ],
    "Address": {
      "Street": "Alameda Xingu",
      "Number": "512",
      "Complement": "21 andar",
      "District": "Alphaville",
      "City": "Barueri",
      "State": "SP"
    }
  },
  "Payment": {
    "BoletoDiscount": 15,
    "Installments": null,
    "MaxNumberOfInstallments": null
  }
}
```

--------------------------------

### Seller Onboarding API

Source: https://docs.cielo.com.br/split/reference/split-pela-api-e-commerce-cielo

Register and query sellers, update fees in bulk, and update banking details.

```APIDOC
## POST /v1/sellers

### Description
Registers a new seller (merchant) in the platform and allows for updating their information, including banking details and fee structures.

### Method
POST

### Endpoint
https://splitonboardingapisandbox.braspag.com.br/v1/sellers

### Parameters
#### Request Body
- **SellerId** (string) - Required - Unique identifier for the seller.
- **Name** (string) - Required - The seller's legal or business name.
- **Document** (object) - Required - Seller's identification document.
  - **Type** (string) - Required - Document type (e.g., CPF, CNPJ).
  - **Value** (string) - Required - Document number.
- **BankingData** (object) - Required - Seller's banking information.
  - **BankCode** (string) - Required - The bank code.
  - **BranchCode** (string) - Required - The branch code.
  - **AccountNumber** (string) - Required - The bank account number.
  - **AccountType** (string) - Required - The type of account (e.g., Checking, Savings).
  - **AccountHolderName** (string) - Required - The name of the account holder.
  - **AccountHolderDocument** (object) - Required - Account holder's document.
    - **Type** (string) - Required - Document type.
    - **Value** (string) - Required - Document number.
- **FeeRates** (array) - Optional - A list of fee rates applicable to the seller.
  - **PaymentMethod** (string) - Required - The payment method the fee applies to (e.g., CreditCard, Boleto).
  - **Rate** (number) - Required - The fee rate (e.g., 0.05 for 5%).
  - **InstallmentCount** (integer) - Optional - The number of installments this rate applies to.

### Request Example
```json
{
  "SellerId": "SELLER789",
  "Name": "Vendedor de Exemplo Ltda",
  "Document": {
    "Type": "CNPJ",
    "Value": "12345678000199"
  },
  "BankingData": {
    "BankCode": "001",
    "BranchCode": "0001",
    "AccountNumber": "12345-6",
    "AccountType": "Checking",
    "AccountHolderName": "Vendedor de Exemplo",
    "AccountHolderDocument": {
      "Type": "CNPJ",
      "Value": "12345678000199"
    }
  },
  "FeeRates": [
    {
      "PaymentMethod": "CreditCard",
      "Rate": 0.045,
      "InstallmentCount": 1
    },
    {
      "PaymentMethod": "Boleto",
      "Rate": 0.01
    }
  ]
}
```

### Response
#### Success Response (201)
- **SellerId** (string) - The unique identifier of the created seller.
- **Status** (string) - The status of the seller registration (e.g., Pending, Active).
- **Message** (string) - A confirmation message.

#### Response Example
```json
{
  "SellerId": "SELLER789",
  "Status": "Active",
  "Message": "Seller registered successfully."
}
```
```

--------------------------------

### Debit Card Payment with Transaction Start Initiator

Source: https://docs.cielo.com.br/gateway-en/reference/create-a-debit-card

This endpoint initiates a debit card transaction with specific details for the transaction start initiator.

```APIDOC
## POST /websites/cielo_br/transactions/initiator

### Description
Initiates a debit card payment transaction, potentially with specific initiator details.

### Method
POST

### Endpoint
/websites/cielo_br/transactions/initiator

### Parameters
#### Request Body
- **MerchantOrderId** (string) - Required - The unique identifier for the merchant's order.
- **Customer** (object) - Required - Information about the customer.
  - **Name** (string) - Required - The customer's full name.
  - **Identity** (string) - Required - The customer's identification number.
  - **IdentityType** (string) - Required - The type of identification (e.g., "CPF").
  - **Email** (string) - Required - The customer's email address.
  - **Birthdate** (string) - Required - The customer's date of birth (YYYY-MM-DD).
  - **IpAddress** (string) - Required - The customer's IP address.
- **Payment** (object) - Required - Payment details.
  - **Provider** (string) - Required - The payment provider (e.g., "Simulado").
  - **Type** (string) - Required - The payment type (e.g., "DebitCard").
  - **Amount** (integer) - Required - The transaction amount in cents.
  - **DebitCard** (object) - Required - Debit card details.
    - **CardNumber** (string) - Required - The debit card number.
    - **Holder** (string) - Required - The cardholder's name.
    - **ExpirationDate** (string) - Required - The card's expiration date (MM/YYYY).
    - **SecurityCode** (string) - Required - The card's security code.
    - **SaveCard** (boolean) - Optional - Whether to save the card for future use.
    - **Brand** (string) - Required - The card brand (e.g., "Master").
  - **Authenticate** (boolean) - Required - Whether to authenticate the transaction.
  - **Recurrent** (boolean) - Optional - Whether the transaction is recurrent.
  - **ReturnUrl** (string) - Required - The URL to return to after the transaction.
  - **Tip** (boolean) - Optional - Whether to include a tip.
  - **ExternalAuthentication** (object) - Required for authentication.
    - **Cavv** (string) - Required - Cardholder Authentication Verification Value.
    - **Xid** (string) - Required - Transaction ID for external authentication.
    - **Eci** (string) - Required - Electronic Commerce Indicator.
    - **Version** (string) - Required - Authentication version.
    - **ReferenceId** (string) - Required - Reference ID for the authentication.

### Request Example
```json
{
  "MerchantOrderId": "202301131052",
  "Customer": {
    "Name": "Aline De Souza",
    "Identity": "12345678909",
    "IdentityType": "CPF",
    "Email": "alinedesouza@email.com.br",
    "Birthdate": "1990-01-01",
    "IpAddress": "127.0.0.1"
  },
  "Payment": {
    "Provider": "Simulado",
    "Type": "DebitCard",
    "Amount": 10000,
    "DebitCard": {
      "CardNumber": "5200000000002151",
      "Holder": "Aline De Souza",
      "ExpirationDate": "03/2031",
      "SecurityCode": "079",
      "SaveCard": false,
      "Brand": "Master"
    },
    "Authenticate": true,
    "Recurrent": false,
    "ReturnUrl": "https://braspag.com.br",
    "Tip": false,
    "ExternalAuthentication": {
      "Cavv": "AAABB2gHA1B5EFNjWQcDAAAAAAB=",
      "Xid": "Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
      "Eci": "5",
      "Version": "2",
      "ReferenceId": "a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
    }
  }
}
```

### Response
#### Success Response (200)
- **TransactionId** (string) - The unique identifier for the transaction.
- **Status** (string) - The status of the transaction.

#### Response Example
```json
{
  "TransactionId": "9876543210",
  "Status": "Initiated"
}
```
```

--------------------------------

### Example Public Key (CSR) Format

Source: https://docs.cielo.com.br/atendimento/docs/como-configurar-o-boleto-registrado-ita%C3%BA-api

This is an example of a public key certificate request file, typically with a .csr extension. It contains the public key information and is sent as 'Credencials.PublicKey' during the onboarding process. This file complements the private key for establishing secure connections.

```text
-----BEGIN CERTIFICATE REQUEST-----
BEEGvjCCAaYCAQAweTEtMCsGA1UEAwwkRTA0MDhhZDAtZTkyOC00OTA3LTliN2QtN2QzMDhmM2U2ZjAyMRowGAYDVQQKDBFDT05TT1JDSU8gSU5URUdSQTESMBAGA1UE
BwwJU0FPIFBBVUxPMQswCQYDVQQIDAJTUDELMAkGA1UEBhMCQlIwggEiMA0GCSqG
SIb3DQEBAQUAA4IBDwAwggEKAoIBAQDFSQxt2LHLQhqI2A\/JJ2uBV+R4bKcM9RDi
4T0S+EW4rYkmedgSnsfmuLQ8WlsWAH0O0cSlr5ozoFdUIo97C\/wD0zuNtmC\/ekQe
KItoef5\/fVkePSbpwPZIQPGCEmDY8M\/wkeI7zok6xF1BBB1S3tqj\/0Snkhtojnp6
Eqdg2yZRTT6E2APVGoTt3rm7583ynAiqhbeBLbYm9jI4Uq5PzOjs03MwS6J7P5lK
WB1LsIt9dHAMAcGkcg2P3\/sBk3qcOw80ZL5oI1h6mU3vJZRS1w8UF\/se95iByDl7
5d\/utrHJeYpxNDGg0UZz7Fwpjr71IMBLHS36Po4jXqJ29EyM8gtlAgMBAAGgADAN
BgkqhkiG9w0BAQ0FAAOCAQEANSNma6rR5WGmzf\/1sjBcTSkVdxX\/jF2EAJgBkLi3
a\/+VQbKFZtecho+5Lh8INfW7L2ldytHJ7mUzez9aLbFmhbtRgJ+o\/gwJC0ATptFY
wxkQeTZhTx\/6nPb2G6RORNLgD1v9PRgF3iKKolLy0fDd2ZpWbmMD+h4ushYezYFu
OiMBDBvjOtVPuSF6EneaBViceeLUMqCYl+xrOt74zoGb7MDa3ukf7jhVoTXBE9V2
otognstT6zODxiD5kIadw13KZdA0ftRFoUg6939IIzH9VK+uyn71+R3lyP\/OD+av
8QBqAYqyGpjQk52j5T3Ua6LIUVUqIZSLPDLc0jkCuvgAZZ==
-----END CERTIFICATE REQUEST-----
```

--------------------------------

### GET /websites/cielo_br/transactions/{paymentId}

Source: https://docs.cielo.com.br/gateway-en/reference/create-a-debit-card

Retrieves the details of a specific payment transaction using its unique PaymentId.

```APIDOC
## GET /websites/cielo_br/transactions/{paymentId}

### Description
Retrieves the details of a specific payment transaction using its unique PaymentId. This endpoint provides comprehensive information about a transaction, including its status, amount, currency, and provider details.

### Method
GET

### Endpoint
`/websites/cielo_br/transactions/{paymentId}`

### Parameters
#### Path Parameters
- **paymentId** (string) - Required - The unique identifier for the payment transaction.

### Request Example
```json
{
  "paymentId": "5b79cfd4-3ea2-4029-bfeb-a651a432aa23"
}
```

### Response
#### Success Response (200)
- **Version** (string) - The API version used for the transaction.
- **ReferenceId** (string) - A unique identifier for the reference of the transaction.
- **Tip** (boolean) - Indicates if a tip was applied to the transaction.
- **PaymentId** (string) - The unique identifier for the payment transaction.
- **Type** (string) - The type of payment method used (e.g., "DebitCard").
- **Amount** (integer) - The transaction amount in cents.
- **ReceivedDate** (string) - The date and time the payment was received.
- **CapturedAmount** (integer) - The amount that has been captured in cents.
- **CapturedDate** (string) - The date and time the payment was captured.
- **Currency** (string) - The currency of the transaction (e.g., "BRL").
- **Country** (string) - The country code where the transaction occurred (e.g., "BRA").
- **Provider** (string) - The payment provider used for the transaction.
- **ExtraDataCollection** (array) - Additional data collected for the transaction.
  - **Name** (string) - The name of the extra data field.
  - **Value** (string) - The value of the extra data field.
- **ReasonCode** (integer) - The code indicating the reason for the transaction status.
- **ReasonMessage** (string) - A message describing the reason for the transaction status.
- **Status** (integer) - The status code of the transaction.
- **ProviderReturnCode** (string) - The return code from the payment provider.
- **ProviderReturnMessage** (string) - The return message from the payment provider.
- **Links** (array) - A list of related links for the transaction.
  - **Method** (string) - The HTTP method for the link.
  - **Rel** (string) - The relation type of the link.
  - **Href** (string) - The URL for the link.

#### Response Example
```json
{
  "Version": "2",
  "ReferenceId": "a24a5d87-b1a1-4aef-a37b-2f30b91274e6",
  "Tip": false,
  "PaymentId": "5b79cfd4-3ea2-4029-bfeb-a651a432aa23",
  "Type": "DebitCard",
  "Amount": 10000,
  "ReceivedDate": "2025-10-23 18:30:38",
  "CapturedAmount": 10000,
  "CapturedDate": "2025-10-23 18:30:39",
  "Currency": "BRL",
  "Country": "BRA",
  "Provider": "Simulado",
  "ExtraDataCollection": [
    {
      "Name": "NomeDoCampo",
      "Value": "ValorDoCampo"
    }
  ],
  "ReasonCode": 0,
  "ReasonMessage": "Successful",
  "Status": 2,
  "ProviderReturnCode": "6",
  "ProviderReturnMessage": "Operation Successful",
  "Links": [
    {
      "Method": "GET",
      "Rel": "self",
      "Href": "https://apiquerysandbox.braspag.com.br/v2/sales/5b79cfd4-3ea2-4029-bfeb-a651a432aa23"
    }
  ]
}
```
```

--------------------------------

### POST /provider/onboarding

Source: https://docs.cielo.com.br/atendimento/docs/como-configurar-o-boleto-registrado-ita%C3%BA-api

Initiates the onboarding process with the Cielo BR provider for 'Itau3' payment type 'Boleto'. Requires merchant credentials in the header and specific provider credentials in the request body.

```APIDOC
## POST /provider/onboarding

### Description
Initiates the onboarding process with the Cielo BR provider for 'Itau3' payment type 'Boleto'. Requires merchant credentials in the header and specific provider credentials in the request body.

### Method
POST

### Endpoint
https://adminservices.pagador.com.br/provider/onboarding

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Header Parameters
- **MerchantId** (GUID) - Required - Identifier of the store.
- **MerchantKey** (string) - Required - Store key.

#### Request Body
- **Provider** (string) - Required - Name of the provider. Use "Itau3".
- **PaymentType** (string) - Required - Payment method type. Use "Boleto".
- **Credencials** (object) - Required - Object containing provider-specific credentials.
  - **PublicKey** (string) - Required - Certificate obtained during dynamic certificate creation.
  - **PrivateKey** (string) - Required - Private key obtained during dynamic certificate creation.
  - **TokenTemporario** (string) - Required - Temporary token obtained from Itaú.
  - **ClientId** (string) - Required - Client ID obtained from Itaú.
  - **Agencia** (string) - Required - Bank agency code from Itaú.
  - **Conta** (string) - Required - Bank account number from Itaú.
  - **Carteira** (string) - Required - Wallet code obtained from Itaú.
  - **Vencimento** (string) - Optional - Number of days for boleto expiration from the current date. If not provided, the current date plus one day will be used.

### Request Example
```json
{
    "Provider": "Itau3",
    "PaymentType": "Boleto",
    "Credencials": {
        "PublicKey": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",
        "PrivateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
        "TokenTemporario": "eyJraWQiOi...f+tRUg==",
        "ClientId": "b0509ad1-e928-4907-9b7d-7d308f3e7g13",
        "Agencia": "2938",
        "Conta": "51122-9",
        "Carteira": "176",
        "Vencimento": "1"
    }
}
```

**Note on PublicKey and PrivateKey:** For Postman (or similar interfaces) to correctly interpret line breaks in certificates or keys, use the escape character `\r\n` within the string. This ensures the content is formatted correctly during the request.

### Response
#### Success Response (200)
(Response details not provided in the input text)

#### Response Example
(Response example not provided in the input text)
```

--------------------------------

### Install Adobe Commerce Braspag Module via Composer

Source: https://docs.cielo.com.br/conectores/docs/adobe-commerce

This snippet demonstrates the steps to install the Braspag payment gateway module for Adobe Commerce using Composer. It requires SSH access to the server and execution within the project's root directory. Ensure you have the correct Composer version and Magento CLI access.

```bash
composer require braspag/magento2-module-braspagpagador
composer update
bin/magento module:enable Braspag_BraspagPagador
bin/magento setup:upgrade
```

--------------------------------

### Onboarding API

Source: https://docs.cielo.com.br/split/reference

APIs for onboarding merchants and managing their configurations.

```APIDOC
## POST /api/merchants

### Description
Registers a seller linked to a master account in the Payment Split.

### Method
POST

### Endpoint
`/api/merchants`

### Parameters
#### Request Body
- **merchantInfo** (object) - Required - Information about the merchant to be registered.
  - **name** (string) - Required - Merchant's name.
  - **document** (string) - Required - Merchant's document number.
  - **category** (string) - Required - Merchant's business category.
  - **masterAccountId** (string) - Required - The ID of the master account.

### Response
#### Success Response (200)
- **merchantId** (string) - The ID of the newly registered merchant.

#### Response Example
```json
{
  "merchantId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

```APIDOC
## GET /api/merchants/{merchant-id}

### Description
Retrieves the data and status of a seller.

### Method
GET

### Endpoint
`/api/merchants/{merchant-id}`

### Parameters
#### Path Parameters
- **merchant-id** (string) - Required - The ID of the merchant.

### Response
#### Success Response (200)
- **merchantId** (string) - The merchant's ID.
- **name** (string) - The merchant's name.
- **status** (string) - The merchant's current status.

#### Response Example
```json
{
  "merchantId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "Example Merchant",
  "status": "Active"
}
```
```

```APIDOC
## PUT /api/agreements/batch

### Description
Updates the same set of fees for all sellers in a batch.

### Method
PUT

### Endpoint
`/api/agreements/batch`

### Parameters
#### Request Body
- **sellerIds** (array of strings) - Required - List of seller IDs to update.
- **feeStructure** (object) - Required - The fee structure to apply.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Fee structure updated for batch of sellers."
}
```
```

```APIDOC
## PATCH /api/v2/agreements/batch

### Description
Enables the Pix payment method in batch for already registered sellers.

### Method
PATCH

### Endpoint
`/api/v2/agreements/batch`

### Parameters
#### Request Body
- **sellerIds** (array of strings) - Required - List of seller IDs to enable Pix for.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Pix payment method enabled for batch of sellers."
}
```
```

```APIDOC
## GET /api/v2/agreements/batch/{requestId}

### Description
Queries if the batch update for Pix was successful for each seller.

### Method
GET

### Endpoint
`/api/v2/agreements/batch/{requestId}`

### Parameters
#### Path Parameters
- **requestId** (string) - Required - The ID of the batch request.

### Response
#### Success Response (200)
- **results** (array of objects) - Results for each seller.
  - **sellerId** (string) - The seller's ID.
  - **status** (string) - The status of the Pix enablement.

#### Response Example
```json
{
  "results": [
    {
      "sellerId": "seller123",
      "status": "Success"
    },
    {
      "sellerId": "seller456",
      "status": "Failed"
    }
  ]
}
```
```

```APIDOC
## POST /api/merchants/{MerchantId}/bank-account/request-update

### Description
Updates the bank account details for a specific seller.

### Method
POST

### Endpoint
`/api/merchants/{MerchantId}/bank-account/request-update`

### Parameters
#### Path Parameters
- **MerchantId** (string) - Required - The ID of the merchant.

#### Request Body
- **bankAccountInfo** (object) - Required - The new bank account details.
  - **accountNumber** (string) - Required - The new account number.
  - **agency** (string) - Required - The new agency number.
  - **bankCode** (string) - Required - The bank code.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Bank account update request submitted."
}
```
```

--------------------------------

### Cielo E-commerce API Request Body Example (Credit Card PaymentToken)

Source: https://docs.cielo.com.br/ecommerce-cielo/docs/integrando-com-o-sop

Example of the JSON payload required for a payment request using a Credit Card PaymentToken. This structure replaces the need for direct card details and is a mandatory field for credit card payments.

```json
{
   "MerchantOrderId":"2017051002",
   "Customer":
   {
     (...)
   },
   "Payment":
   {
     (...)
     "CreditCard":{
         "PaymentToken":"eedcb896-40e1-465b-b34c-6d1119dbb6cf"
     }
   }
}
```

--------------------------------

### API Request Example in JSON

Source: https://docs.cielo.com.br/gateway/reference/alterando-os-dados-de-pagamento-da-recorr%C3%AAncia

This JSON object demonstrates a sample API request for credit card transactions. It includes transaction details, customer information, and necessary credentials. Note that 'Provider' should be 'Simulado' for sandbox environments and credentials are not required in that case.

```json
{
  "Type": "CreditCard",
  "Amount": "20000",
  "Installments": 3,
  "Country": "USA",
  "Currency": "USD",
  "SoftDescriptor": "Mensagem",
  "Provider": "Simulado",
  "CreditCard": {
    "Brand": "Master",
    "Holder": "Nome do Portador",
    "CardNumber": "5412217070050381",
    "ExpirationDate": "05/2035"
  },
  "Credentials": {
    "Code": "9999999",
    "Key": "D8888888",
    "Password": "LOJA9999999",
    "Username": "#Braspag2018@NOMEDALOJA#",
    "Signature": "001"
  }
}
```

--------------------------------

### Credit Card Payment Example (JSON)

Source: https://docs.cielo.com.br/ecommerce-cielo/reference/criar-pagamento-multibeneficios

An example of a JSON payload representing a credit card payment transaction for Cielo Brazil. This includes customer details, billing information, and specific credit card data such as card number, holder name, expiration date, security code, and brand. It also shows the amount and number of installments.

```json
{
  "MerchantOrderId": "Loja123456",
  "Customer": {
    "Name": "Aline de Souza",
    "Email": "compradorteste@teste.com",
    "Birthdate": "1991-01-02",
    "Address": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "Billing": {
      "Street": "Rua Neturno",
      "Number": "12345",
      "Complement": "Sala 123",
      "Neighborhood": "Centro",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BR",
      "ZipCode": "20080123"
    }
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Installments": 1,
    "CreditCard": {
      "CardNumber": "4532110000001234",
      "Holder": "Aline de Souza",
      "ExpirationDate": "12/2030",
      "SecurityCode": "123",
      "Brand": "Visa"
    }
  },
  "Voucher": true
}
```

--------------------------------

### API Request Example

Source: https://docs.cielo.com.br/gateway/reference/alterando-dados-do-comprador

Provides a sample JSON request body for the API, including buyer's personal information (Name, Email, Birthdate, Identity) and their address and delivery address details. This example demonstrates the expected structure and data types for a successful request.

```json
{
  "Name": "Nome do Comprador",
  "Email": "customer@teste.com",
  "Birthdate": "1999-12-12",
  "Identity": "22658954236",
  "IdentityType": "CPF",
  "Address": {
    "Street": "Rua Teste",
    "Number": "174",
    "Complement": "AP 201",
    "ZipCode": "05426200",
    "City": "São Paulo",
    "State": "SP",
    "Country": "BRA",
    "District": "Alphaville"
  },
  "DeliveryAddress": {
    "Street": "Outra Rua Teste",
    "Number": "123",
    "Complement": "AP 111",
    "ZipCode": "21241111",
    "City": "Qualquer Lugar",
    "State": "QL",
    "Country": "BRA",
    "District": "Teste"
  }
}
```

--------------------------------

### Payment Request Example

Source: https://docs.cielo.com.br/gateway/reference/antifraude-aci

Provides a sample JSON request for a payment transaction. It includes merchant order ID, customer details (name, identity, email, phone, address), and payment information such as provider, type, amount, and installments.

```json
{
  "MerchantOrderId": "123456",
  "Customer": {
    "Name": "Comprador Teste",
    "Identity": "12345678910",
    "IdentityType": "CPF",
    "Email": "comprador@braspag.com.br",
    "Birthdate": "1991-01-02",
    "Phone": "5521976781114",
    "mobile": "5511940028922",
    "Address": {
      "Street": "Alameda Xingu",
      "Number": "512",
      "Complement": "27 andar",
      "ZipCode": "12345987",
      "City": "São Paulo",
      "State": "SP",
      "Country": "BR",
      "District": "Alphaville"
    }
  }
}
```

--------------------------------

### POST /v2/sales/

Source: https://docs.cielo.com.br/gateway/reference/pix-api

Cria uma transação com QR code Pix. Disponível tanto para ambiente de Sandbox quanto de Produção.

```APIDOC
## POST /v2/sales/

### Description
Cria uma transação com QR code Pix.

### Method
POST

### Endpoint
- Sandbox: `https://apisandbox.braspag.com.br/v2/sales/`
- Produção: `https://api.braspag.com.br/v2/sales/`

### Parameters
#### Path Parameters
Nenhum.

#### Query Parameters
Nenhum.

#### Request Body
O corpo da requisição deve conter os detalhes da transação Pix.
Exemplo:
```json
{
  "MerchantOrderId": "string",
  "Customer": {
    "Name": "string",
    "Email": "string",
    "Identity": {
      "Type": "CPF",
      "Value": "string"
    },
    "Birthdate": "YYYY-MM-DD"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 100,
    "Installments": 1,
    "Pix": {
      "QrCode": {
        "Image": "string",
        "ExpirationDate": "YYYY-MM-DDTHH:mm:ss"
      }
    },
    "SoftDescriptor": "string"
  }
}
```

### Request Example
```json
{
  "MerchantOrderId": "20240101001",
  "Customer": {
    "Name": "John Doe",
    "Email": "johndoe@email.com",
    "Identity": {
      "Type": "CPF",
      "Value": "11111111111"
    },
    "Birthdate": "1990-01-01"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 10000,
    "Installments": 1,
    "Pix": {
      "QrCode": {
        "Image": "base64EncodedImage",
        "ExpirationDate": "2024-01-01T10:00:00"
      }
    },
    "SoftDescriptor": "MYMERCHANT"
  }
}
```

### Response
#### Success Response (200)
Retorna os detalhes da transação criada, incluindo o status e informações do QR Code Pix.
Exemplo:
```json
{
  "MerchantOrderId": "20240101001",
  "Status": 1,
  "PaymentResult": {
    "Tid": "string",
    "AuthorizationCode": "string",
    "PaymentId": "string",
    "Amount": 10000,
    "Type": "CreditCard",
    "Pix": {
      "QrCode": {
        "Image": "string",
        "ExpirationDate": "2024-01-01T10:00:00"
      }
    }
  }
}
```

#### Response Example
```json
{
  "MerchantOrderId": "20240101001",
  "Status": 1,
  "PaymentResult": {
    "Tid": "1234567890",
    "AuthorizationCode": "123456",
    "PaymentId": "abcdef123456",
    "Amount": 10000,
    "Type": "CreditCard",
    "Pix": {
      "QrCode": {
        "Image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
        "ExpirationDate": "2024-01-01T10:00:00"
      }
    }
  }
}
```

### Error Handling
Códigos de erro padrão da API Braspag/Cielo serão retornados em caso de falha.
```