Advanced button

This option allows you to direct your client to make a payment using CambioReal with little or no programming needed. We recommend this button for sites that have various types of products and services, which can be accumulated in one purchase. This will work as a shopping cart style checkout. See below:

1. Customer chooses products or services in your store.
2. The form with the CambioReal's checkout button must be inserted in the shopping cart. The customer is directed, along with the purchase data, to CambioReal's website.
3. On CambioReal's website, the customer makes the payment.
4. Customer is redirected back to your site, to a purchase completion page.

HTML Form

In the example you can see an HTML form that directs the buyer to the payment page.

HTML form that directs the buyer to the payment page

<!-- START FORM CambioReal -->
<form action="https://www.cambioreal.com/pagamento/carrinho" method="post">
  <!-- Mandatory Fields -->
  <input type="hidden" name="token" value="_YOUR_TOKEN_" />
  <input type="hidden" name="account" value="_YOUR_ACCOUNT_" />
  <input type="hidden" name="url_callback" value="_YOUR_URL_CALLBACK_" />
  <input type="hidden" name="url_error" value="_YOUR_URL_ERROR_" />
  <!-- Optional fields for billing setup -->
  <input type="hidden" name="currency" value="BRL" />
  <input type="hidden" name="take_rates" value="1" />
  <input type="hidden" name="duplicate" value="1" />
  <input type="hidden" name="expiration_days" value="1" />
  <!-- Maximum purchase session time in minutes (default 30min) -->
  <input type="hidden" name="time_session" value="_TIME_" />
  <!-- Payment reference code on your system (optional) -->
  <input type="hidden" name="reference" value="_YOUR_ORDER_REFERENCE_" />
  <!-- Product 1 -->
  <input type="hidden" name="produtos[0][descricao]" value="_NAME_PRODUCT_1_" />
  <input type="hidden" name="produtos[0][valor]" value="_VALUE_PRODUCT_1_" />
  <input type="hidden" name="produtos[0][ref]" value="_REF_PRODUCT_1_" />
  <!-- Product 2,3,.... (optional) -->
  <input type="hidden" name="produtos[1][descricao]" value="test" />
  <input type="hidden" name="produtos[1][valor]" value="80.00" />
  <input type="hidden" name="produtos[1][ref]" value="T1" />
  <!-- Customer details (optional) -->
  <input name="client_name" type="hidden" value="Nome do cliente" />
  <input name="client_email" type="hidden" value="nome@mail.com" />
  <input name="client_cpf" type="hidden" value="XXXXXXXXXXX" />
  <!-- Button style (Please see the documentation for other sizes) -->
  <input
    type="image"
    src="https://www.cambioreal.com/botoes/bnt-cr-105x116.png"
    type="submit"
    alt="Pague com CambioReal"
  />
</form>
<!-- //END FORM CambioReal -->

The payment page address in CambioReal, as shown in the example, is:

Request

POST https://www.cambioreal.com/pagamento/carrinho

Parameters For Form Filling

The parameters available on the Payment via HTML expected by the payment form are listed in the table below.

Authentication

The token and account inputs are sent to the developer's email along with this documentation, in case of loss, request the company to resend the e-mail.

Redirection

End of session

When the client makes a payment on CambioReal's checkout environment, it will be redirected to your site through the input url_callback. You can configure to which page it will be. It can also be used to transmit the ID of the purchase for conversion record.

Example

<input
  type="hidden"
  name="url_callback"
  value="http://www.seudominio.com/success?id=2"
/>

Errors

When the information passed by the HTML form is invalid, the client is redirected to the site.

Use the url_error input to set the error page on your site, Note: If your site does not have a specific error page, set the url to your shopping cart

Possible errors:

• Session expired
• Invalid information in HTML form
• Total value less than USD 50.00

Reference

Use the input reference to enter the order reference code to your system. This will be very useful if you want to integrate the backend of your e-commerce with CambioReal, to use our API of query of the status of transactions.

Each transaction generated may be related to a sequential number chosen accordingly to the company's preference, such as the transaction ID or order number.

The use of this parameter is exclusively for internal use of the company. The client does not have access to this information at any point in the checkout process.

The use of this parameter is optional and can be viewed on the transaction details, which can be accessed in the company's account panel, on CambioReal's website.

Configuration

The configuration fields are all optional, some have default values and others have global configuration on the Company Dashboard, in the online account menu.

Base Currency

Use the input currency to set the base currency to perform the payment request calculations.

Default value: USD

Available values: USD, BRL

Take Charges

Use the take_rates input to enable or disable the charging of fees, payment method costs and IOF from the company. If enabled, the company assumes the fees and they will not be passed on to the customer.

Default value: Defined in the Company Panel

Available values: 0, 1

Duplicate

Use the input duplicate to enable or disable the duplicate issue of expired transactions.

Default value: Defined in the Company Panel

Available values: 0, 1

Expiration

Use the expiration_days input to set the total in days of billing time, after the expiration is not possible to generate another transaction. To use this option, the (duplicate) method must be enabled.

Default value: 0

Available values: from 0 to 10

Session Time

When customers are directed to the CambioReal website, by default, they have 30 minutes to generate the transaction, if they exceed this time, the client will be redirected to url url_error defined above.

Some e-commerces work with time-limited promotions and end-of-stock products, in which they limit and decrease the client's session time to avoid that the client makes a payment of product that has been sold out during a long session, so it is recommended to shorten this time.

Products

It must be informed at least one product or service in the HTML form and the sum of the total value of the products must exceed USD 50.00.

To send more than one product, use the following form:

<!-- Produto 1 -->
<input type="hidden" name="produtos[0][descricao]" value="_NAME_PRODUCT_1_" />
<input type="hidden" name="produtos[0][valor]" value="_VALUE_PRODUCT_1_" />
<input type="hidden" name="produtos[0][ref]" value="_REF_PRODUCT_1_" />
<!-- Produto 2 -->
<input type="hidden" name="produtos[1][descricao]" value="_NAME_PRODUCT_2_" />
<input type="hidden" name="produtos[1][valor]" value="_VALUE_PRODUCT_2_" />
<input type="hidden" name="produtos[1][ref]" value="_REF_PRODUCT_2_" />
<!-- Produto 3 -->
<input type="hidden" name="produtos[2][descricao]" value="_NAME_PRODUCT_3_" />
<input type="hidden" name="produtos[2][valor]" value="_VALUE_PRODUCT_3_" />
<input type="hidden" name="produtos[2][ref]" value="_REF_PRODUCT_3_" />

The data of each product are composed by 3 items, they are:

Description:

Name of the product or service offered.

Value:

Partial amount of this item charged.

Reference (optional):

Use this field if you want to add more details to your description. For example, the parcel number, a number of a product / service, customer account.

Customer Details

Thinking about the convenience of your clients, we suggest to send their details, so they won't have to re-enter this information on the payment screen.

Button

You can change the button to any other element of your preference, as long as it makes the submission of the HTML form.

CambioReal also offers some ready-made button options for submitting the form and they are listed in the table below:

BUTTON	SIZE	LINK
	95 x 85 pixels	https://www.cambioreal.com/botoes/bnt-cr-95x85.png
	105 x 116 pixels	https://www.cambioreal.com/botoes/bnt-cr-105x116.png
	155 x 51 pixels	https://www.cambioreal.com/botoes/bnt-cr-155x51.png
	203 x 37 pixels	https://www.cambioreal.com/botoes/bnt-cr-203x37.png
	523 x 148 pixels	https://www.cambioreal.com/botoes/bnt-cr-523x148.png

Direct API

Base URL for Sandbox:

https://sandbox.cambioreal.com

Base URL for Production:

https://www.cambioreal.com

CambioReal's Direct API works with any kind of e-commerce, by seamlessly connecting with your shopping cart. When a customer chooses CambioReal's payment method, it will be redirected to the external checkout where very quickly it can complete the payment. Once the customer has completed all fields and successfully paid the order,it will be redirected back to your store. With the Direct API, you can receive notifications of when a transaction changes status and query its data.

This section's content:

• Authentication
• Api Requests
• Payment Request
• Get Transaction Data
• Cancel Payment Request
• Amount Calculator
• Status Notification

Authentication

Authentication in our API is performed in 3 steps to ensure greater security and convenience in transactions:

1. The client's APP ID is first validated.
2. The client's APP SECRET is verified, if it is valid and matches the registration.
3. And lastly, it is validated if the received request comes from an IP or Hostname / Domain identical to the one registered by the client in the panel.

Acquiring your credentials

1. Access CambioReal for business Dashboard.

2. Go to Integration.

   

3. Then click on the Direct API tab.

   

4. Fill in the fields with the corresponding data.

   • Developer name: Person responsible for integrating magento with cambioreal.
   • Developer e-mail: The e-mail we will send instructions and credentials.
   • Select the bank account in which you would like to receive your payments: All payments made through this button will be sent to this account.
   • Select the type of address to restrict access from your website to our API: The authentication will be made via ip or hostname/domain of your website. E.g.: Website IP: 54.208.129.87 / Website Hostname: cambioreal.com
   • Notification URL: It is through this url that our server will send a notification informing that your transactions status changed in our payment system. Format: https://{YOUR_SITE}/cambioreal/payment/notify

5. Click on the Create API access button.

6. Get your generated API ID and TOKEN and add them to each request via the basic authorization header.

Authorization: Basic base64({AppID}:{AppSecret})

Example:

Authorization: Basic MTUwMDAwMDAwMDo5MzU2MmFlMzljYjI4MjNiNzllNzRlYTc2MzAxMmZmZjVkZjJhYjUxOTAyNjI=

Authentication Error Codes

Example of Error Response (401):

{
    "status": "error",
    "code": "EMPTY_APP_ID",
    "message": "Unauthorized",
    "errors": [],
}

The possible error codes can be returned in the authentication process, they are:

• EMPTY_APP_ID - APP ID not found in the request.
• EMPTY_APP_SECRET - APP SECRET not found in the request.
• USER_NOT_FOUND - User not found due to invalid credentials.
• USER_NOT_ACTIVATED - Credentials not enabled.
• ACCOUNT_NOT_FOUND - Company account not found.
• IP_NOT_MATCH - Access is blocked for this IP.
• HOST_NOT_MATCH - Access is blocked for the IP of this hostname.
• BILLING_DISABLED - API requests are not allowed for this company.

Api Requests

All requests have four fields in common in the returned responses:

Example of Success Response:

{
    "status": "success",
    "message": null,
    "errors": null,
    "data": {
        ...
    }
}

Example of Error Response:

{
    "status": "error",
    "message": "Message error example.",
    "errors": [
        "Error example 1 in field x.",
        ...
    ],
    "data": null,
}

Response fields:

Payment Request v1

This method will create a payment request in our system and return the redirect URL for your customer to access our checkout where they will make the payment. In this step you should also enter the return URL to your site (url_callback field) where the customer will be directed back after payment.

Request

Example Request:

{
    "order_id": "123456789",
    "amount": 1004.00,
    "currency": "USD",
    "client": {
        "name": "Johnny Depp",
        "email": "johnny.depp@gmail.com"
    },
    "duplicate": 0,
    "take_rates": 0,
    "url_callback": "https://my-website.com/cambioreal/success",
    "url_error": "https://my-website.com/cambioreal/error",
    "products": [
        {
            "descricao": "iPhone 14 Pro",
            "base_value": 999.00,
            "valor": 999.00,
            "qty": 1,
            "ref": "iphone-internal-ref",
            "category": "iPhone",
            "brand": "Apple",
            "sku": "APH14PRO8173812739"
        },
        {
            "descricao": "Shipping",
            "base_value": 10.00,
            "valor": 10.00,
            "ref": "Priority Mail International"
        },
        {
            "descricao": "Bonus",
            "base_value": -5.00,
            "valor": -5.00,
            "ref": "Discount CODE123"
        }
    ]
}

POST /service/v1/checkout/request

Fields used in the request:

Customer object:

Customer billing/shipping address object:

Product object:

Response

Example Response:

{
    "status": "success",
    "data": {
        "id": 530,
        "token": "e82b97cf652e91344f86510907b32daa5df8f13fdda41",
        "code": "BRSL12171530",
        "expires_at": null,
        "created_at": "2019-12-17 12:16:15",
        "checkout": "https://sandbox.cambioreal.com/pagamento/solicitacao/e82b97cf652e91344f86510907b32daa5df8f13fdda41"
    }
}

Payment Request response fields:

Subscription

This method will create a payment request in our system and return the details of the subscription that will be automatically processed by our system, generating a monthly charge at the established amount. Please note that credit cards are the only accepted method of payment.

Request

Example Request:

{
    "order_id": "123456789",
    "amount": 1004.00,
    "currency": "USD",
    "client": {
        "name": "Johnny Depp",
        "email": "johnny.depp@gmail.com"
    },
    "duplicate": 0,
    "take_rates": 0,
    "url_callback": "https://my-website.com/cambioreal/success",
    "url_error": "https://my-website.com/cambioreal/error",
    "products": [
        {
            "descricao": "iPhone 14 Pro",
            "base_value": 999.00,
            "valor": 999.00,
            "qty": 1,
            "ref": "iphone-internal-ref",
            "category": "iPhone",
            "brand": "Apple",
            "sku": "APH14PRO8173812739"
        },
        {
            "descricao": "Shipping",
            "base_value": 10.00,
            "valor": 10.00,
            "ref": "Priority Mail International"
        },
        {
            "descricao": "Bonus",
            "base_value": -5.00,
            "valor": -5.00,
            "ref": "Discount CODE123"
        }
    ],
    "schedule": {
        "type": "subscription",
        "send_at": "2024-08-15 16:02:50",
        "free_trial_days": 7
    }
}

POST /service/v1/checkout/request

Fields used in the request:

Schedule object:

Customer object:

Customer billing/shipping address object:

Product object:

*All product fields are mandatory for for a retail company.

Response

Example Response:

{
    "status": "success",
    "data": {
        "amount": 35,
        "currency": "USD",
        "scheduled": true,
        "schedule_type": "subscription",
        "sent_at": "2024-01-26T14:05:00.000000Z",
        "repeat_until": "indeterminate",
        "repeat_every": "month",
        "repeat_how_many_months": "indeterminate"
    }
}

Payment Request response fields:

Monthly Payment

This method will create a monthly payment that will send a request email to the customer where he will checkout with all available payment methods.

Request

Example Request:

{
    "order_id": "123456789",
    "amount": 1004.00,
    "currency": "USD",
    "client": {
        "name": "Johnny Depp",
        "email": "johnny.depp@gmail.com"
    },
    "duplicate": 0,
    "take_rates": 0,
    "url_callback": "https://my-website.com/cambioreal/success",
    "url_error": "https://my-website.com/cambioreal/error",
    "products": [
        {
            "descricao": "iPhone 14 Pro",
            "base_value": 999.00,
            "valor": 999.00,
            "qty": 1,
            "ref": "iphone-internal-ref",
            "category": "iPhone",
            "brand": "Apple",
            "sku": "APH14PRO8173812739"
        },
        {
            "descricao": "Shipping",
            "base_value": 10.00,
            "valor": 10.00,
            "ref": "Priority Mail International"
        },
        {
            "descricao": "Bonus",
            "base_value": -5.00,
            "valor": -5.00,
            "ref": "Discount CODE123"
        }
    ],
    "schedule": {
        "type": "monthly",
        "send_at": "2024-08-15 16:02:50",
        "repeat_how_many_months": 10,
        "free_trial_days": 7
    }
}

POST /service/v1/checkout/request

Fields used in the request:

Schedule object:

Customer object:

Customer billing/shipping address object:

Product object:

*All product fields are mandatory for for a retail company.

Response

Example Response:

{
    "status": "success",
    "data": {
        "amount": 35,
        "currency": "USD",
        "scheduled": true,
        "schedule_type": "monthly",
        "sent_at": "2024-01-26T14:05:00.000000Z",
        "repeat_until": "2024-10-26T14:05:00.000000Z",
        "repeat_every": "month",
        "repeat_how_many_months": "10"
    }
}

Payment Request response fields:

Schedule Payment

This method will create a scheduling of your request via email to the customer. Where they will checkout with all available payment methods.

Request

Example Request:

{
    "order_id": "123456789",
    "amount": 1004.00,
    "currency": "USD",
    "client": {
        "name": "Johnny Depp",
        "email": "johnny.depp@gmail.com"
    },
    "duplicate": 0,
    "take_rates": 0,
    "url_callback": "https://my-website.com/cambioreal/success",
    "url_error": "https://my-website.com/cambioreal/error",
    "products": [
        {
            "descricao": "iPhone 14 Pro",
            "base_value": 999.00,
            "valor": 999.00,
            "qty": 1,
            "ref": "iphone-internal-ref",
            "category": "iPhone",
            "brand": "Apple",
            "sku": "APH14PRO8173812739"
        },
        {
            "descricao": "Shipping",
            "base_value": 10.00,
            "valor": 10.00,
            "ref": "Priority Mail International"
        },
        {
            "descricao": "Bonus",
            "base_value": -5.00,
            "valor": -5.00,
            "ref": "Discount CODE123"
        }
    ],
    "schedule": {
        "type": "scheduling",
        "send_at": "2024-08-15 16:02:50",
    }
}

POST /service/v1/checkout/request

Fields used in the request:

Schedule object:

Customer object:

Customer billing/shipping address object:

Product object:

*All product fields are mandatory for for a retail company.

Response

Example Response:

{
    "status": "success",
    "data": {
        "amount": 35,
        "currency": "USD",
        "scheduled": true,
        "schedule_type": "monthly",
        "sent_at": "2024-01-26T14:05:00.000000Z",
    }
}

Payment Request response fields:

Payment Request v2

This method will create a payment request and a transaction for your customer to pay the order without having to access our checkout (transparent payment), bringing more convenience and transparency to your customer.

Request

Example Request:

{
    "order_id": "123456789",
    "amount": 1004.00,
    "currency": "USD",
    "payment_method": "pix",
    "client": {
        "name": "Johnny Depp",
        "email": "johnny.depp@gmail.com",
        "document": "000.000.000-00",
        "birth_date": "2000-01-20",
        "phone": "5511999999999",
        "ip": "127.0.0.1",
        "address": {
            "state": "SP",
            "city": "São Paulo",
            "zip_code": "01310-930",
            "district": "Bela Vista",
            "street": "Avenida Paulista",
            "number": "2000"
        }
    },
    "duplicate": 0,
    "take_rates": 0,
    "products": [
        {
            "descricao": "iPhone 14 Pro",
            "base_value": 999.00,
            "valor": 999.00,
            "qty": 1,
            "ref": "iphone-internal-ref",
            "category": "iPhone",
            "brand": "Apple",
            "sku": "APH14PRO8173812739"
        },
        {
            "descricao": "Shipping",
            "base_value": 10.00,
            "valor": 10.00,
            "ref": "Priority Mail International"
        },
        {
            "descricao": "Bonus",
            "base_value": -5.00,
            "valor": -5.00,
            "ref": "Discount CODE123"
        }
    ]
}

POST /service/v2/checkout/request

Fields used in the request:

Client object for customers already registered with CambioReal:

Client object for new Customers:

Client address object:

Client file object:

Product object:

List of required files for individual:

List of required files for company:

Response

Example successful response:

{
    "status": "success",
    "data": {
        "id": "e82b97cf652e91344f86510907b32daa5df8f13fdda41",
        "code": "BRSL12171530",
        "transaction": {
            "payment_method": "pix",
            "currency": "BRL",
            "amount": 59.58,
            "code": "BR01038246",
            "expires_at": "2023-01-03",
            "ticket_url": "https://sandbox.cambioreal.com/pagamento/transaction/usa/3738dd51f3ac88ea8a243d873cafe12763b46e8cab797/0dea828e6bf4d5d3de5c29c68029e24cf2ff9c65?t=1672769170",
            "barcode": "data:image/svg+xml;base64,PD94b...",
            "number": "00020101021226990014br.gov.bcb.pix...",
            "terms": "Ao efetuar o pagamento, o pagador declara que leu e concordou com os Termos e Condições..."
        }
    }
}

Example error response:

{
    "status": "error",
    "message": "Falha ao realizar transação. Tente novamente!",
    "code": "CLIENT_NOT_REGISTERED"
}

Payment Request response fields:

Transaction object:

Get Transaction Data

This method will return the data from a previously created payment request by token.

Request

GET /service/v1/checkout/get/{token}

Response

Example Response:

{
    "status": "success",
    "message": null,
    "errors": null,
    "data": {
        "id": 530,
        "token": "e82b97cf652e91344f86510907b32daa5df8f13fdda41",
        "code": "BRSL12171530",
        "ref": null,
        "currency": "USD",
        "amount": 300,
        "take_rates": false,
        "duplicate": false,
        "expired": false,
        "expires_in": null,
        "expires_at": null,
        "status": "AGUARDANDO_CLIENTE",
        "payment_method": null,
        "client": {
            "name": "Client name",
            "email": "client.name@cambioreal.com"
        },
        "ticket": "https://sandbox.cambioreal.com/pagamento/solicitacao/e82b97cf652e91344f86510907b32daa5df8f13fdda41",
        "created_at": "2019-12-17 12:16:15",
        "products": [
            {
                "desc": "Order #0001",
                "amount": 300,
                "qty": 1,
                "ref": null
            }
        ],
        "paid_by": {
            "name": "Client name",
            "email": "client.name@cambioreal.com"
        }
    }
}

Transaction Data response fields:

Cancel Payment Request

You can cancel requests, but only if your customer has not yet paid. To cancel, you only need to enter the payment request token.

Request

POST /service/v1/checkout/cancel/{token}

Example of Success Response:

{
    "status": "success",
    "message": "Solicitação cancelada com sucesso!",
    "errors": null,
    "data": null
}

Example of Error Response:

{
    "status": "error",
    "message": "Falha ao cancelar solicitação.",
    "errors": [
        "O status atual desta transação não permite mais ser alterado, entre em contato conosco."
    ],
    "data": null
}

Amount Calculator

This method is used to simulate the total amount to be paid by the customer, it also returns the exchange rate and other fees.

Request

POST /service/v1/checkout/simulator

Fields used in the request:

Response

PIX Response Example:

{
    "status": "success",
    "data": {
        "currency": "USD",
        "amount": 300,
        "price": 6.45,
        "fee": 0,
        "issue_fee": 0,
        "transaction_fee": 0,
        "method_fee": 0,
        "method_fee_usd": 0,
        "iof": 6.4483,
        "iof_percentage": 0.38,
        "rate": 5.6564,
        "rate_direction": "up",
        "result": 1703.37,
        "vet": 5.6779,
        "estimated_delivery": "2023-01-05T11:00:00.000000Z",
        "payment_method": "pix"
    }
}

Credit Card Response Example:

{
    "status": "success",
    "data": {
        "currency": "USD",
        "amount": 300,
        "price": 110.14,
        "fee": 0,
        "issue_fee": 0,
        "transaction_fee": 0,
        "method_fee": 103.21,
        "method_fee_usd": 18,
        "iof": 6.9291,
        "iof_percentage": 0.38,
        "rate": 5.7341,
        "rate_direction": "up",
        "result": 1830.37,
        "vet": 6.10123,
        "estimated_delivery": "2023-01-05T11:00:00.000000Z",
        "payment_method": "credit_card",
        "installments": [
            {
                "installments": 1,
                "amount": 1830.37,
                "fee": 103.21,
                "total": 1830.37,
                "beneficiary": 300
            },
            ...
            {
                "installments": 12,
                "amount": 174.03,
                "fee": 360.22,
                "total": 2088.35,
                "beneficiary": 300
            }
        ]
    }
}

Calculator response fields:

Credit Card installment object:

*The currency is based on the data[currency] choice in the request.

Status Notification

With the notification URL set when creating credentials, you can receive notifications from our system every time a transaction changes its status. Our system only sends the transaction identifiers, id and token, the status query should be done upon receipt of the notification.

When your system receives a notification at the configured URL, it should respond with HTTP 200 status so that our system understands that the notification was received correctly. If not, our system will try to notify you two more times.

We recommend saving the data received from notifications and creating a standalone process that performs status queries so that it does not affect performance or data is lost when the notification process runs.

Example Notification:

{
    "id": 530,
    "token": "e82b97cf652e91344f86510907b32daa5df8f13fdda41"
}

Notification data is sent via POST using Content-Type: application/x-www-form-urlencoded, and has the following fields:

To check the transaction status, simply query the transaction data using the method already cited above, Get Transaction Data.

Possible statuses for a transaction:

• PENDENTE_ACCOUNT - Company bank account is pending approval.
• AGUARDANDO_CLIENTE - Waiting for customer to generate the transaction.
• BOLETO_GERADO - Transaction generated.
• BOLETO_EXPIRADO - Transaction expired.
• BOLETO_CANCELADO - Transaction canceled.
• SOLICITACAO_RECUSADA - Customer declined the payment request.
• SOLICITACAO_INVALIDA - Invalid payment request.
• SOLICITACAO_CANCELADA - Company canceled the payment request.
• SOLICITACAO_PAGO - Payment request paid.
• SOLICITACAO_FINALIZADA - Payment request sent for payment to beneficiary.
• SOLICITACAO_EXPIRADA - Payment request expired.
• REFUND_REQUESTED - Refund requested.
• REFUNDED - Refund executed.

Update transaction status for testing

So far, the only test scenarios available are BOLETO_EXPIRADO and SOLICITACAO_PAGO. After the payment request is generated, you must create a transaction in our checkout before requesting a status change.

PUT /service/v1/checkout/{token}

Fields used in the request:

PHP Library

This library enables you to integrate CambioReal Direct API with any PHP application.

This section's content:

• 1. Requirements
• 2. Installation
• 3. Setup
• 4. Request and Payment
• 5. Notification and Status
• 6. Amount simulator
• 7. Examples
• 8. Sandbox

Requirements

• PHP >= 7.3
• cURL

Installation

Download the latest version of the cambioreal-lib.zip

Download

Setup

To use the CambioReal PHP library you need to setup your app id and app secret.

<?php

\CambioReal\Config::setAppId('your-app-id');
\CambioReal\Config::setAppSecret('your-app-secret');

If you need to change other settings, you can use the following function call:

<?php

require_once __DIR__ . '/../src/autoload.php';

\CambioReal\Config::set([
    'appId'      => 'your-app-id',
    'appSecret'  => 'your-app-secret',
    'testMode' => true,
]);

You can change the following settings:

• appId: your app id. It will be different in test and production modes.
• appSecret: your app secret. It will be different in test and production modes.
• testMode: enable or disable the test mode. The default value is false.

To create a new API request, just call one of the following methods on the \CambioReal\CambioReal class and supply it with the request parameters:

• \CambioReal\CambioReal::cancel
• \CambioReal\CambioReal::get
• \CambioReal\CambioReal::request

Request and Payment

With the library installed and configured, you must call the method \CambioReal\CambioReal::request, which will create a payment request in our system and return the redirect URL for your customer to access our checkout where they will make the payment.

In this step you should also enter the return URL to your site (url_callback field) where the customer will be directed after payment.

Example Request:

{
  "url_callback": "https://seudominio.com/callback_cambioreal_success", // URL to return to when the customer successfully pays.
  "url_error": "https://seudominio.com/callback_cambioreal_error", // URL to return to when an error occurs in the payment process.
  "client": {
    "name": "John Test",
    "email": "john@test.com"
  },
  "currency": "USD",
  "amount": 1605.0,
  "order_id": "_your_control_number_",
  "duplicate": 0, // Allow to customer generate another transaction after expiration. Not required, if not informed the account configuration will be used.
  "due_date": 1, // Number of days the payment request will be valid to. It's not mandatory.
  "products": [
    {
      "descricao": "Laptop i7",
      "base_value": 800.0,
      "valor": 1600.0,
      "qty": 2,
      "ref": "_your_control_number_for_the_product_"
    },
    {
      "descricao": "Frete",
      "base_value": 5.0,
      "valor": 5.0,
      "ref": "São Paulo - SP"
    }
  ]
}

Notification and Status

This is how our proccess of notification of status change happens:

When a transaction changes status in our system, it notifies your site via a form-data POST by informing the transaction id and token.

Your application will receive this data as a normal POST, as if receiving data from a form (form-data, not json or xml):

• $request->input('id');
• $request->input('token');

With this information it's possible to make a query through our API to request what is the current status.

In the response received from this query you can identify what is the transaction within your system through the reference passed at the time the request was generated.

Example of data sent in notification:

{
  "id": 5,
  "token": "88ba76feb3b6623e6aaa03d88e1620f55a9d4b8790500"
}

To query the notified transaction status, use the get method, which performs a GET request to endpoint /service/v1/checkout/get/{YOUR_TOKEN}, where {YOUR_TOKEN} is the identifier of the transaction to query.

Example query response from a transaction:

{
  "status": "success",
  "message": null,
  "errors": null,
  "data": {
    "id": 5,
    "token": "88ba76feb3b6623e6aaa03d88e1620f55a9d4b8790500",
    "code": "BRSL03051005",
    "ref": null,
    "currency": "USD",
    "amount": 150,
    "take_rates": false,
    "duplicate": false,
    "expired": false,
    "expires_in": null,
    "expires_at": null,
    "status": "BOLETO_GERADO",
    "created_at": "2019-03-13 11:20:07",
    "payment_method": "boleto"
  }
}

The ref field will be the order reference within your system previously passed through the field order_id in the creation of the request.

Amount simulator

The customer sees the simulation in our checkout, but if you want to make it available on your system there is an endpoint to it.

To perform a simulation of values, call the \CambioReal\CambioReal::simulator method or send a request using the POST method to endpoint /service/v1/checkout/simulator.

Simulation Example:

{
  "currency": "USD", // Simulation Currency
  "amount": 30, // Amount to be converted
  "take_rates": 1, // Option if the company wants to assume the fees (shipping fee, iof, ...)
  "payment_method": "boleto" // Payment Method (boleto, ted)
}

Example of the response received:

{
  "status": "success",
  "message": null,
  "errors": null,
  "data": {
    "currency": "USD",
    "amount": 30, // Amount requested
    "price": 13.87, // Total cost price (taxes)
    "fee": 1.99, // USD service fee charged
    "method_fee": 3.95, // Amount charged in BRL according to payment method
    "iof": 1.3613, // IOF to be paid
    "iof_percentage": 1.1, // IOF percentage (1.1%)
    "rate": 4.3023, // Rate of the moment
    "result": 129.07, // Total Conversion Amount
    "vet": 4.81964 // VET (Total Effective Value)
  }
}

Examples

You can find the following examples in the cambioreal-lib.latest.zip/examples folder.

These examples demonstrate the usage of the CambioReal PHP Library.

• examples/bootstrap.php - Initial setup (Where credentials should be placed).
• examples/checkout.php - Request (A url will be returned to redirect the customer to our checkout).
• examples/get.php - Request for get transaction details.
• examples/simulator.php - Amount simulation.

Request to create a payment request:

<?php

require_once 'bootstrap.php';

$response = \CambioReal\CambioReal::request(array(
    'url_callback' => 'https://seudominio.com/callback_cambioreal_success',
    'url_error' => 'https://seudominio.com/callback_cambioreal_error',
    'client' => array(
        'name'  => 'John Test',
        'email' => 'john@test.com',
    ),
    'currency'  => 'USD',
    'amount'    => 130.00,
    'order_id'  => '10000052',
    'duplicate' => false,
    'due_date'  => null,
    'products'  => array(
        array(
            'descricao'  => 'Laptop i7',
            'base_value' => 800.00,
            'valor'      => 1600.00,
            'qty'        => 2,
            'ref'        => 1,
        ),
        array(
            'descricao'  => 'Frete',
            'base_value' => 5.00,
            'valor'      => 5.00,
            'ref'        => 'São Paulo - SP',
        ),
    ),
));

Request to cancel previously created payment request:

<?php

$response = \CambioReal\CambioReal::cancel(array(
    'id'    => $request->data->id,
    'token' => $request->data->token
));

Request to get transaction details:

<?php

$response = \CambioReal\CambioReal::get(array(
    'id'    => $request->data->id,
    'token' => $request->data->token,
));

Possible statuses of a get.php request:

• PENDENTE_ACCOUNT - Company bank account is pending approval.
• AGUARDANDO_CLIENTE - Waiting for customer to generate the transaction.
• BOLETO_GERADO - Transaction generated.
• BOLETO_EXPIRADO - Transaction expired.
• BOLETO_CANCELADO - Transaction canceled.
• SOLICITACAO_RECUSADA - Customer declined payment request.
• SOLICITACAO_INVALIDA - Invalid request.
• SOLICITACAO_CANCELADA - Company canceled the request.
• SOLICITACAO_PAGO - Request paid.
• SOLICITACAO_FINALIZADA - Request sent for payment to beneficiary.
• SOLICITACAO_EXPIRADA - Request expired.
• REFUNDED - Refund requested.

Request to perform amount simulation.

<?php

$request = \CambioReal\CambioReal::simulator(array(
    'currency'       => 'USD',
    'amount'         => 50.00,
    'take_rates'     => false,
    'payment_method' => 'boleto',
));

Sandbox

We have prepared a test environment. Access it with your credentials (https://sandbox.cambioreal.com).

Credentials should be added to the request header:

• X-APP-ID: your_app_id
• X-APP-SECRET: your_app_secret

If you send request data in JSON format, you must specify the following header:

• Content-Type: application/json

Magento

For companies using the Magento e-commerce system, this extension allows you to direct your customer to make payments at CambioReal automatically.

This section's content:

• Authentication
• 1. Setup
• 2. Install the extension
• 3. Update the extension settings

CambioReal Magento Extension

Version: 1.1.3

Compatibility: For Magento 1.6, 1.7, 1.8 and 1.9

Download

Authentication

Authentication in our API is performed in 3 steps to ensure greater security and convenience in transactions.

1. The client's APP ID is first validated.
2. The client's APP SECRET is verified, if it is valid and matches the registration.
3. And lastly, it is validated if the received request comes from an IP or Hostname / Domain identical to the one registered by the client in the panel.

1. Setup

1.1. Access CambioReal for business Dashboard.

1.2. Go to Integration.

1.3. Then click on the Direct API tab.

1.4. Fill in the fields with the corresponding data.

• Developer name: Person responsible for integrating magento with cambioreal.
• Developer e-mail: The e-mail we will send instructions and credentials.
• Select the bank account in which you would like to receive your payments: All payments made through this button will be sent to this account.
• Select the type of address to restrict access from your website to our API: The authentication will be made via ip or hostname/domain of your website. E.g.: Website IP: 54.208.129.87 / Website Hostname: cambioreal.com
• Notification URL: It is through this url that our server will send a notification informing that your transactions status changed in our payment system. Format: https://{YOUR_SITE}/cambioreal/payment/notify

1.5. Click on the Create API access button.

2. Install the extension

2.1. Download the latest version of the CambioReal Magento extension and extract its contents to the root folder of your Magento installation.

2.2. Go to your store administrative area.

2.3. If you have cache enabled, you will need to flush it at System > Cache Management, by clicking on the button "Flush Magento Cache".

2.4. If everything went perfectly, CambioReal payment system settings will appear in System > Configuration > Payment Methods > CambioReal.

3. Update the extension settings

3.1. Enable the CambioReal payment extension.

3.2. Add the App ID and App Secret you received in your e-mail from CambioReal.

3.3. Perform the other settings as needed and you're done! The CambioReal payment module will be fully operational.

Understand every item on the configuration page in the list below :

• Enabled: CambioReal can be used as a payment method or not.
• Title: Identifier for this payment method on checkout.
• App ID: Unique Public Key.
• App Secret: Unique Secret key, keep it safe and do not expose this information.
• Test mode: No for Production mode and Yes for Test mode (sandbox).
• Duplicate: Allow to generate another transaction after expiration.
• Due date: The day by which a product must be paid.
• Open order status: The status when a order is still open.
• Paid order status: The status when a order has already been paid.
• Canceled order status: The status when a order has been canceled.

Magento 2

This section's content:

• 1. Setup
• 2. Install the extension
• 3. Update the extension settings

CambioReal Magento 2 Extension

Version: 1.2.1

Compatibility: For Magento 2.0/2.1/2.2

Download

Compatibility: For Magento >= 2.3

Download

1. Setup

1.1. Access CambioReal for business Dashboard.

1.2. Go to Integration.

1.3. Then click on the Direct API tab.

1.4. Fill in the fields with the corresponding data.

• Developer name: Person responsible for integrating magento with cambioreal.
• Developer e-mail: The e-mail we will send instructions and credentials.
• Select the bank account in which you would like to receive your payments: All payments made through this button will be sent to this account.
• Select the type of address to restrict access from your website to our API: The authentication will be made via ip or hostname/domain of your website. E.g.: Website IP: 54.208.129.87 / Website Hostname: cambioreal.com
• Notification URL: It is through this url that our server will send a notification informing that your transactions status changed in our payment system. Format: https://{YOUR_SITE}/cambioreal/payment/notify

1.5. Click on the Create API access button.

2. Install the extension

2.1. Download the CambioReal Magento 2 extension and extract its contents to the root folder of your Magento installation.

2.2. Open the terminal from the Magento 2 folder and run the following commands:

php bin/magento setup:upgrade

php bin/magento setup:static-content:deploy

php bin/magento indexer:reindex

2.3. If it’s necessary, you have to flush the cache at System > Cache Management, by clicking on the button "Flush Magento Cache".

2.4. If everything was done correctly, you will see CambioReal settings at System > Configuration > Sales > Payment Methods > CambioReal.

3. Update the extension settings

3.1. Enable the CambioReal payment extension.

3.2. Add the App ID and App Secret you received in your e-mail from CambioReal.

3.3. Change the other settings as needed.

Understand every item on the configuration page in the list below:

Credentials

• App Secret: Unique Secret key, keep it safe and do not expose this information.
• App ID: Unique Public Key.
• Sandbox: No for Production mode and Yes for Sandbox mode.
• Allowed Return URLs: Where the customer will be directed after the payment.
• Allowed Notification URLs: It is through this url that our server will send a notification informing that your transactions status changed in our payment system.

Options

• Enabled: CambioReal can be used as a payment method or not.
• Title: Identifier for this payment method on checkout.
• Duplicate: Allow to generate another transaction after expiration.
• Payment currency: Base currency is the currency your site works with internally and Frontend currency is the currency shown to the client when viewing a product.
• Canceled order status: The status when a order has been canceled.
• Paid order status: The status when a order has already been paid.
• Open order status: The status when a order is still open.
• Processing order status: The status when a order is being processed.
• Payment from Applicable Countries: Choose between all allowed countries or specific countries that CambioReal accepts payments.
• Payment from Specific Countries: If you chose specific countries in the previous option, you have to choose the countries you want to allow payments with CambioReal.

WooCommerce

This plugin creates the integration between the WooCommerce platform and CambioReal, and redirect customers for payment.

This section's content:

• 1. Setup
• 2. Install the plugin
• 3. Update the plugin settings
• 4. Woocommerce settings

CambioCheckout WooCommerce plugin

Version: 2.1.2

Compatibility: For WooCommerce 3.0.0 or later

Download

1. Setup

1.1. Access CambioReal for business Dashboard.

1.2. Go to Integration.

1.3. Then click on the Direct API tab.

1.4. Fill in the fields with the corresponding data.

• Developer name: Person responsible for integrating magento with cambioreal.
• Developer e-mail: The e-mail we will send instructions and credentials.
• Select the bank account in which you would like to receive your payments: All payments made through this button will be sent to this account.
• Select the type of address to restrict access from your website to our API: The authentication will be made via ip or hostname/domain of your website. E.g.: Website IP: 54.208.129.87 / Website Hostname: cambioreal.com
• Notification URL: It is through this url that our server will send a notification informing that your transactions status changed in our payment system. Format: https://{YOUR_SITE}/cambioreal/payment/notify

1.5. Click on the Create API access button.

2. Install the plugin

Follow this instructions to install CambioCheckout Payment Gateway on WordPress Woocommerce.

2.1. Download the CambioCheckout Woocommerce plugin.

2.2. Extract cambioreal.woocommerce.latest.zip file contents to the plugins folder (wp-content/plugins) of your Wordpress installation.

2.3. Enable the CambioCheckout payment plugin.

3. Update the plugin settings

3.1. Click Settings in the activated plug-in or on CambioCheckout in sidebar admin menu.

3.2. Add the App ID and the App Secret that you generated or received in your e-mail from CambioReal.

3.3. Change the other settings as needed.

Understand every item on the configuration page in the list below:

• Enable/Disable: CambioCheckout can be used as a payment method or not.
• API Credentials:
  a. App ID: Unique Public Key.
  b. App Secret: Unique Secret key, keep it safe and do not expose this information.
• CambioReal Sandbox: This option enables sandbox mode and disables production mode. The CambioReal sandbox is used to test payments.
• Debug Log: This option allows Woocommerce to record all errors that occur when executing a transaction.
• Title: Identifier for this payment method on checkout.
• Description: Description to the payment method that the client will see on checkout along with the title.
• Duplicate: Allow to generate another transaction after expiration without the customer having to create another order in the system.
• Take Rates: No fees will be charged from the customer (includes iof). They will be discounted from the business final payment.
• Show cart simulation: This option shows in the cart the exchange rate and the value with IOF to be paid by the customer at the checkout of CambioReal.

Before exiting make sure you saved the changes.

4. Woocommerce Settings

In some cases, Woocommerce orders automatically expire after some period if not paid. This happens if inventory management is enabled on the platform, to get around this problem, you must disable the "Hold stock" timeout or increase it to a considerable amount of time. But beware, boletos can take up to 3 business days to be paid, so if you are using this payment method, it is important to disable this Woocommerce automation.

Contact us

To contact us with any questions or suggestions, use support@cambioreal.com or via chat at https://www.cambioreal.com/en/contact-us.