Developer Api Documentation

  • Home
  • Developer Api Documentation

Introduction

This section describes the FFS Cash charges gateway API.

FFS Cash is RESTFul . This means we use predictable, resource-oriented URLs to do operations. The API itself speaks exclusively in JSON , including errors. You can use the API in test mode, which does not affect your live data.

Security

We use Open SSL Encrypt and API Key to authenticate requests. That means you need to generate a private key to sign your requests to our API, and register the corresponding public key with us so we can validate those requests.

We are a payment facilitator, all of our card payment institutions use the 3DS security standard and they are PCI-DSS certified. 3DS, or EMV 3DS, is an e-commerce authentication protocol that enables secure processing of card transactions and aims to increase security and reliability in transaction flow for both the seller and the consumer, minimize fraud occurrences, and maintain good transaction conversion. The Payment Card Industry Data Security Standard (PCI-DSS) is an information security standard used to handle credit cards from major card brands.

To release the production environment, it is necessary to provide the IPs that will be using our API. We follow all the best practices required by the market.

Supported Currencies

This section describes the currencies supported by FFS Cash

FFS Cash allows to make transaction with below currencies. Any new currency may update in future.

Currency Name Currency Symbol Currency Code
Brazilian Real R$ BRL

Get The Api Key

This section describes how you can get your api key.

To get your Api Key, please contact us via email api@ffs.cash

Create a credit card billing

This section describes the process of create the billing.

To create the billing follow the example code and be careful with the perameters. You will need to make request with these following API end points.

Production End Point: https://api.ffs.cash/billing

Sandbox End Point: https://sandbox.ffs.cash/billing

Request Method: POST

Status Available: NEW, AUTHORIZED, WAITING, PAID, IN_ANALYSIS, OVERDUE, DECLINED, CANCELED

Request to the end point with the following parameters below.

Param Name Param Type Description
api-key (Header) string Required Your API key
type string Required Use: CREDIT_CARD
reference_id string (50) Required You Internal identifier
description string (100) Required Description of billing
amount integer Required Billing amount.
installments integer Required Number of installments.
card_number integer (16) Required Card number.
card_exp_month integer (2) Required Card expiration month.
card_exp_year integer (4) Required Card expiration year.
card_security_code integer (4) Required Card security code.
card_holder_name integer (16) Required Card holder name.
customer_fullname string (50) Required Customer full name.
customer_email string (50) Required Customer valid email.
customer_cellphone string (20) Required Customer cell phone.
customer_cpf string (16) Required Customer CPF.
customer_birthdate string (YYYY-MM-DD) Required Customer birthdate.
customer_address string (100) Required Customer address.
customer_address_number string (10) Required Customer address number.
customer_address_complement string (50) Required Customer address complement.
customer_address_district string (50) Required Customer address district.
customer_address_city string (20) Required Customer address city.
customer_address_state string (20) Required Customer address state.
customer_address_country string (20) Required Customer address country.
customer_address_postal_code string (10) Required Customer address postal code.
Example cURL
curl 
-H 'Content-type: application/x-www-form-urlencoded' 
-H 'api-key: {{API-KEY}}' 
-d 'data=openssl_encrypt
{
    "type": "CREDIT_CARD",
    "reference_id": "0001",
    "description": "Motivo da cobrança",
    "amount": "1000",
    "installments": "12",
    "card_number": "4111111111111111",
    "card_exp_month": "03",
    "card_exp_year": "2026",
    "card_security_code": "123",
    "card_holder_name": "Jose da Silva",
    "customer_fullname": "Jose da Silva",
    "customer_email": "joao@email.com",
    "customer_cellphone": "(11)998111111",
    "customer_cpf": "33333333333",
    "customer_birthdate": "1980-12-30",
    "customer_address": "Rua dos testes",
    "customer_address_number": "123",
    "customer_address_complement": "Apto 12",
    "customer_address_district": "Itaim",
    "customer_address_city": "São Paulo",
    "customer_address_state": "SP",
    "customer_address_country": "Brazil",
    "customer_address_postal_code": "06121-120"
}
' 
-X POST https://sandbox.ffs.cash/billing
Example Responses

//Error Response.
{
    "code": "401",
    "message": {
            "status": "error",
            "description": "Unauthorized",
        },
}

//Success Response.
{
    "code": 200,
    "message":
        {
            "status": "ok",
            "description": "Successful request",
        },
    "response": {
          "id": "BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD",
          "reference_id": "0001",
          "status": "AUTHORIZED",
          "created_at": "2019-04-17T20:07:07.002-02",
          "paid_at": "2019-04-17T20:07:07.002-02",
          "description": "Motivo do pagamento",
          "amount": {
            "value": 1000,
            "currency": "BRL",
            "summary": {
              "total": 1000,
              "paid": 0,
              "refunded": 0
            }
          }
    }
}

Create a bank slip billing

This section describes the process of create the billing.

To create the billing follow the example code and be careful with the perameters. You will need to make request with these following API end points.

Production End Point: https://api.ffs.cash/billing

Sandbox End Point: https://sandbox.ffs.cash/billing

Request Method: POST

Status Available: NEW, AUTHORIZED, WAITING, PAID, IN_ANALYSIS, OVERDUE, DECLINED, CANCELED

Request to the end point with the following parameters below.

Param Name Param Type Description
api-key (Header) string Required Your API key
type string Required Use: BANK_SLIP
reference_id string (50) Required You Internal identifier
description string (100) Required Description of billing
amount integer Required Billing amount.
installments integer Required Number of installments.
customer_fullname string (50) Required Customer full name.
customer_email string (50) Required Customer valid email.
customer_cellphone string (20) Required Customer cell phone.
customer_cpf string (16) Required Customer CPF.
customer_birthdate string (YYYY-MM-DD) Required Customer birthdate.
customer_address string (100) Required Customer address.
customer_address_number string (10) Required Customer address number.
customer_address_complement string (50) Required Customer address complement.
customer_address_district string (50) Required Customer address district.
customer_address_city string (20) Required Customer address city.
customer_address_state string (20) Required Customer address state.
customer_address_country string (20) Required Customer address country.
customer_address_postal_code string (10) Required Customer address postal code.
Example cURL
curl 
-H 'Content-type: application/x-www-form-urlencoded' 
-H 'api-key: {{API-KEY}}' 
-d 'data=openssl_encrypt
{
    "type": "BANK_SLIP",
    "reference_id": "0001",
    "description": "Motivo da cobrança",
    "amount": "1000",
    "installments": "12",
    "customer_fullname": "Jose da Silva",
    "customer_email": "joao@email.com",
    "customer_cellphone": "(11)998111111",
    "customer_cpf": "33333333333",
    "customer_birthdate": "1980-12-30",
    "customer_address": "Rua dos testes",
    "customer_address_number": "123",
    "customer_address_complement": "Apto 12",
    "customer_address_district": "Itaim",
    "customer_address_city": "São Paulo",
    "customer_address_state": "SP",
    "customer_address_country": "Brazil",
    "customer_address_postal_code": "06121-120"
}'
-X POST https://sandbox.ffs.cash/billing
Example Responses

//Error Response.
{
    "code": "401",
    "message": {
            "status": "error",
            "description": "Unauthorized",
        },
}

//Success Response.
{
    "code": 200,
    "message":
        {
            "status": "ok",
            "description": "Successful request",
        },
    "response": {
          "id": "BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD",
          "type": "BANK_SLIP",
          "reference_id": "0001",
          "status": "PAID",
          "created_at": "2019-04-17T20:07:07.002-02",
          "paid_at": "2019-04-17T20:07:07.002-02",
          "description": "Motivo do pagamento",
          "amount": {
            "value": 1000,
            "currency": "BRL",
            "summary": {
              "total": 1000,
              "paid": 0,
              "refunded": 0
            },
           "bank_slips": {
                "1": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_1",
                "2": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_2",
                "3": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_3",
                "4": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_4",
                "5": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_5",
                "6": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_6",
                "7": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_7",
                "8": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_8",
                "9": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_9",
                "10": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_10",
                "11": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_11",
                "12": "https://sandbox.ffs.cash/billing/bank_slip/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_12",
            }, 
            
          }
    }
}

Create a Pix billing

This section describes the process of create the billing.

To create the billing follow the example code and be careful with the perameters. You will need to make request with these following API end points.

Production End Point: https://api.ffs.cash/billing

Sandbox End Point: https://sandbox.ffs.cash/billing

Request Method: POST

Status Available: NEW, AUTHORIZED, WAITING, PAID, IN_ANALYSIS, OVERDUE, DECLINED, CANCELED

Request to the end point with the following parameters below.

Param Name Param Type Description
api-key (Header) string Required Your API key
type string Required Use: PIX
reference_id string (50) Required You Internal identifier
description string (100) Required Description of billing
amount integer Required Billing amount.
customer_fullname string (50) Required Customer full name.
customer_email string (50) Required Customer valid email.
customer_cellphone string (20) Required Customer cell phone.
customer_cpf string (16) Required Customer CPF.
customer_birthdate string (YYYY-MM-DD) Required Customer birthdate.
customer_address string (100) Required Customer address.
customer_address_number string (10) Required Customer address number.
customer_address_complement string (50) Required Customer address complement.
customer_address_district string (50) Required Customer address district.
customer_address_city string (20) Required Customer address city.
customer_address_state string (20) Required Customer address state.
customer_address_country string (20) Required Customer address country.
customer_address_postal_code string (10) Required Customer address postal code.
Example cURL
curl 
-H 'Content-type: application/x-www-form-urlencoded' 
-H 'api-key: {{API-KEY}}' 
-d 'data=openssl_encrypt
{
    "type": "PIX",
    "reference_id": "0001",
    "description": "Motivo da cobrança",
    "amount": "1000",
    "customer_fullname": "Jose da Silva",
    "customer_email": "joao@email.com",
    "customer_cellphone": "(11)998111111",
    "customer_cpf": "33333333333",
    "customer_birthdate": "1980-12-30",
    "customer_address": "Rua dos testes",
    "customer_address_number": "123",
    "customer_address_complement": "Apto 12",
    "customer_address_district": "Itaim",
    "customer_address_city": "São Paulo",
    "customer_address_state": "SP",
    "customer_address_country": "Brazil",
    "customer_address_postal_code": "06121-120"
}'
-X POST https://sandbox.ffs.cash/billing
Example Responses

//Error Response.
{
    "code": "401",
    "message": {
            "status": "error",
            "description": "Unauthorized",
        },
}

//Success Response.
{
    "code": 200,
    "message":
        {
            "status": "ok",
            "description": "Successful request",
        },
    "response": {
          "id": "BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD",
          "type": "PIX",
          "reference_id": "0001",
          "status": "PAID",
          "created_at": "2019-04-17T20:07:07.002-02",
          "paid_at": "2019-04-17T20:07:07.002-02",
          "description": "Motivo do pagamento",
          "amount": {
            "value": 1000,
            "currency": "BRL",
            "summary": {
              "total": 1000,
              "paid": 0,
              "refunded": 0
            },
           "pix": {
                "pix_qrcode": "https://sandbox.ffs.cash/billing/pix/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD_1.jpg",
                "pix_key": "123e4567-e12b-12d1-a456-426655440000",
                "pix_copy_paste": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426655440000 5204000053039865802BR5913Fulano de Tal6008BRASILIA62070503***63041D3D",
            }, 
            
          }
    }
}

Consult a billing

This section describes the process of consult the billing.

To consult the billing follow the example code and be careful with the perameters. You will need to make request with these following API end points.

Production End Point: https://api.ffs.cash/billing/{id}

Sandbox End Point: https://sandbox.ffs.cash/billing/{id}

Request Method: GET

Status Available: NEW, AUTHORIZED, WAITING, PAID, IN_ANALYSIS, OVERDUE, DECLINED, CANCELED

Request to the end point with the following parameters below.

Param Name Param Type Description
api-key (Header) string Required Your API key
id string (50) Required Billing ID
Example cURL
curl https://sandbox.ffs.cash/billing/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD
-H 'Content-type: application/x-www-form-urlencoded' 
-H 'api-key: {{API-KEY}}'
Example Responses

//Error Response.
{
    "code": "401",
    "message": {
            "status": "error",
            "description": "Unauthorized",
        },
}

//Success Response.
{
    "code": 200,
    "message":
        {
            "status": "ok",
            "description": "Successful request",
        },
    "response": {
          "id": "BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD",
          "reference_id": "0001",
          "status": "CANCELED",
          "created_at": "2019-04-17T20:07:07.002-02",
          "paid_at": "2019-04-17T20:07:07.002-02",
          "description": "Motivo do pagamento",
          "amount": {
            "value": 1000,
            "currency": "BRL",
            "summary": {
              "total": 1000,
              "paid": 0,
              "refunded": 1000
            }
          }
    }
}

Cancel a billing

This section describes the process of cancel the billing.

To cancel the billing follow the example code and be careful with the perameters. You will need to make request with these following API end points.

Production End Point: https://api.ffs.cash/billing/{id}/cancel

Sandbox End Point: https://sandbox.ffs.cash/billing/{id}/cancel

Request Method: POST

Request to the end point with the following parameters below.

Param Name Param Type Description
api-key (Header) string Required Your API key
id string (50) Required Billing ID
Example cURL
curl 
-H 'Content-type: application/x-www-form-urlencoded' 
-H 'api-key: {{API-KEY}}'
-X POST https://sandbox.ffs.cash/billing/BEYOUPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD/cancel
Example Responses

//Error Response.
{
    "code": "401",
    "message": {
            "status": "error",
            "description": "Unauthorized",
        },
}

//Success Response.
{
    "code": 200,
    "message":
        {
            "status": "ok",
            "description": "Successful request",
        },
    "response": {
          "id": "BEYOYPAY_D32A01A9-92A6-4755-B21D-7B6A1291F7AD",
          "reference_id": "0001",
          "status": "CANCELED",
          "created_at": "2019-04-17T20:07:07.002-02",
          "paid_at": "2019-04-17T20:07:07.002-02",
          "description": "Motivo do pagamento",
          "amount": {
            "value": 1000,
            "currency": "BRL",
            "summary": {
              "total": 1000,
              "paid": 0,
              "refunded": 1000
            }
          }
    }
}