Quickstart: with pre-evaluation

This integration has two variations: one where the installments options are shown by us and another where the installments are shown by you (provided for by us through an endpoint). To start using banca.me buy now, pay later API, follow the following steps:

Get your API keys
API Keys
You will need an API Key for each merchant that integrates with banca.me.
Evaluate customer and get installment options
Optional: determine user selected installment option
Installment Options
This step is when you show the user the installment options that are available and he/she chooses one on your frontend. In this endpoint you determine which option the user chooses and therefore we will not show the installment options.
Create a widget session through a widgetToken
Load the widget using the widgetToken
Handle post-payments events
Verify transaction through backend
Make your first payment
widget session
widgetToken is valid for 10 minutes after creation, then it will be invalid

Step 1: Get your API Keys

Every interaction with the banca.me API must be authenticated with the API Keys of your banca.me account. If an interaction with the API does not include your API Key or includes an incorrect API Key, banca.me will return an error. Every banca.me account has two key pairs: one corresponds to the test mode (beta), while the other corresponds to the actual production API environment. Your API Keys will be available to you through 1Password.

Step 2: Evaluate customer and get installment options

To get the installment options for a customer, you'll need to make a POST request to the /partner/pre-loan-request/bnpl endpoint with the customer's information. Here's how you can do it in different programming languages:

Axios JS
Node Fetch
PHP
Python
Curl

Axios JS
const axios = require('axios');

async function getInstallmentOptions() {
  try {
    const response = await axios.post('https://api.banca.me/partner/pre-loan-request/bnpl',
      new URLSearchParams({
        idNumber: '12345678-9',
        amount: 100000,
        entityId: 'ex-46df3310759e9000',
        externalTrxId: 'your-transaction-id'
      }), {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/x-www-form-urlencoded'
        }
    });
    console.log(response.data);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}

Node Fetch
async function getInstallmentOptions() {
  try {
    const response = await fetch('https://api.banca.me/partner/pre-loan-request/bnpl', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        idNumber: '12345678-9',
        amount: 100000,
        entityId: 'ex-46df3310759e9000',
        externalTrxId: 'your-transaction-id'
      })
    });
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}

PHP
<?php
$url = 'https://api.banca.me/partner/pre-loan-request/bnpl';
$data = array(
    'idNumber' => '12345678-9',
    'amount' => 100000,
    'entityId' => 'ex-46df3310759e9000',
    'externalTrxId' => 'your-transaction-id'
);
$options = array(
    'http' => array(
        'header'  => "Content-Type: application/x-www-form-urlencoded\r\n" .
                     "Authorization: Bearer YOUR_API_KEY\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) {
    // Handle error
} else {
    $response = json_decode($result, true);
    print_r($response);
}
?>

Python
import requests
import json
def get_installment_options():
    url = "https://api.banca.me/partner/pre-loan-request/bnpl"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/x-www-form-urlencoded"
    }
    data = {
        "idNumber": "12345678-9",
        "amount": 100000,
        "entityId": "ex-46df3310759e9000",
        "externalTrxId": "your-transaction-id"
    }
    try:
        response = requests.post(url, headers=headers, data=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        raise

Curl
curl -X POST 'https://api.banca.me/partner/pre-loan-request/bnpl' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d 'idNumber=12345678-9&amount=100000&entityId=ex-46df3310759e9000&externalTrxId=your-transaction-id'

The response will include the available installment options for the customer:

{
  "data": {
    "installmentOptions": [
      {
        "installments": 3,
        "amount": 33333,
        "total": 100000
      },
      {
        "installments": 6,
        "amount": 16666,
        "total": 100000
      }
    ]
  }
}

preApproveId

Remember to store the preApproveId because you will need it for future requests.

Step 3 (Optional): Determine user selected installment option

Once you have the installment options, you can create a loan request with the selected option. Here's how to do it in different programming languages:

Axios JS
Node Fetch
PHP
Python
Curl

Curl
curl -X POST 'https://api.banca.me/partner/pre-loan-request/loan-request' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d 'preApproveId=pre-approve-id-123&installmentOption=3&externalTrxId=your-transaction-id&amount=100000'

Axios JS
const axios = require('axios');

async function createLoanRequest() {
  try {
    const response = await axios.post('https://api.banca.me/partner/pre-loan-request/loan-request',
      new URLSearchParams({
        preApproveId: 'pre-approve-id-123',
        installmentOption: 3,
        externalTrxId: 'your-transaction-id',
        amount: 100000
      }), {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/x-www-form-urlencoded'
        }
    });
    console.log(response.data);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}

Node Fetch
async function createLoanRequest() {
  try {
    const response = await fetch('https://api.banca.me/partner/pre-loan-request/loan-request', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        preApproveId: 'pre-approve-id-123',
        installmentOption: 3,
        externalTrxId: 'your-transaction-id',
        amount: 100000
      })
    });
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}

PHP
<?php
$url = 'https://api.banca.me/partner/pre-loan-request/loan-request';
$data = array(
    'preApproveId' => 'pre-approve-id-123',
    'installmentOption' => 3,
    'externalTrxId' => 'your-transaction-id',
    'amount' => 100000
);
$options = array(
    'http' => array(
        'header'  => "Content-Type: application/x-www-form-urlencoded\r\n" .
                     "Authorization: Bearer YOUR_API_KEY\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) {
    // Handle error
} else {
    $response = json_decode($result, true);
    print_r($response);
}
?>

Python
import requests
import json
def create_loan_request():
    url = "https://api.banca.me/partner/pre-loan-request/loan-request"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/x-www-form-urlencoded"
    }
    data = {
        "preApproveId": "pre-approve-id-123",
        "installmentOption": 3,
        "externalTrxId": "your-transaction-id",
        "amount": 100000
    }
    try:
        response = requests.post(url, headers=headers, data=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        raise

The response will include the loan request details:

{
  "data": {
    "loanRequestId": "loan-request-123",
    "step": "AUTHORIZATION",
    "preApproveId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

The step is the step in which we will load the widget. The available steps are described in the Steps section.

Step 4: Create a widgetToken

Using your API Key you need to create a widgetToken from your backend. Always create the widgetToken from your backend, or a malicious user could create widgetToken on your behalf. For more details about this endpoint, check out the widget token API reference. Here is an example of how to create a widgetToken:

Axios JS
Node Fetch
PHP
Python
Curl

Axios JS
const axios = require('axios');

const response = await axios.post('https://api.banca.me/partner/widget/start',
  new URLSearchParams({
    amount: 100000,
    externalTrxId: 'your-transaction-id',
    entityId: 'ex-46df3310759e9000',
    email: 'customer@example.com'
  }), {
    headers: {
      'Accept': 'application/x-www-form-urlencoded',
      'Authorization': 'Bearer <token>'
    }
});
console.log(response.data);

Curl
curl -L -X POST 'https://api.banca.me/partner/widget/start' \
-H 'Accept: application/x-www-form-urlencoded' \
-H 'Authorization: Bearer <token>' \
-d 'preApproveId=123e4567-e89b-12d3-a456-426614174000'

Node Fetch
const response = await fetch('https://api.banca.me/partner/widget/start', {
  method: 'POST',
  headers: {
    'Accept': 'application/x-www-form-urlencoded',
    'Authorization': 'Bearer <token>'
  },
  body: new URLSearchParams({
    preApproveId: '123e4567-e89b-12d3-a456-426614174000',
  })
});
const data = await response.json();

PHP
<?php
$url = 'https://api.banca.me/partner/widget/start';
$data = array(
    'preApproveId' => '123e4567-e89b-12d3-a456-426614174000'
);
$options = array(
    'http' => array(
        'header'  => "Content-Type: application/x-www-form-urlencoded\r\n" .
                     "Accept: application/x-www-form-urlencoded\r\n" .
                     "Authorization: Bearer <token>\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) {
    // Handle error
} else {
    $response = json_decode($result, true);
    print_r($response);
}
?>

Python
import requests
from urllib.parse import urlencode
def create_widget_token():
    url = "https://api.banca.me/partner/widget/start"
    headers = {
        "Accept": "application/x-www-form-urlencoded",
        "Authorization": "Bearer <token>"
    }
    data = {
        "amount": 100000,
        "externalTrxId": "your-transaction-id",
        "preApproveId": "123e4567-e89b-12d3-a456-426614174000"
    }
    try:
        response = requests.post(url, headers=headers, data=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        raise

Example response:

{
  "data": {
    "accepted": true,
    "widgetToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Widget Token is temporary

widgetToken is temporary and will expire in 10 minutes.

There are two ways to do this. The recommend way is to use our JavaScript library. Please refer to Installation and usage section. The other option to initiate payment is simply to rediret the customer to the payment URL in banca.me. The URL is pagos.banca.me/?widgetToken=<widgetToken>&publicKey=<publicKey>&successReturnUrl=<successReturnUrl>&errorReturnUrl=<errorReturnUrl>. The user will be redirected after 10 seconds to the errorReturnUrl?preApproveId=<preApproveId>&externalTrxId=<externalTrxId> or successReturnUrl?preApproveId=<preApproveId>&externalTrxId=<externalTrxId> in the event of an error (or rejection) and succesful payment respectively. Remember that every variable must be URL encoded. With the preApproveId you have to check whether the transaction was succesful. Please see step 5.

Error return URL

preApproveId could be undefined if the user is redirected to the error URL.

Please refer to Widget Callbacks section. Here, banca.me sends a onSuccess event when the payment has been successful. Use the widget guide to recieve this events and run actions.

Step 7: Verify transaction through backend

After receiving the onSuccess event, you should verify the transaction. This can be done using our webhook or by verifying it through our REST API through your backend using your externalTrxId. We recommend using the webhook. The webhook must be registered through this endpoint. For more details about this endpoint, check out the verify transaction API reference. Here's how to do it:

Axios JS
Node Fetch
PHP
Python
Curl

Curl
curl -X GET 'https://api.banca.me/partner/pre-approve/your-transaction-id/loan' \
-H 'Authorization: Bearer YOUR_API_KEY'

Axios JS
const axios = require('axios');

async function verifyTransaction() {
  try {
    const response = await axios.post('https://api.banca.me/partner/pre-approve/your-transaction-id/loan', {}, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    console.log(response.data);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}

Node Fetch
async function verifyTransaction() {
  try {
    const response = await fetch('https://api.banca.me/partner/pre-approve/your-transaction-id/loan', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}

PHP
<?php
$url = 'https://api.banca.me/partner/pre-approve/your-transaction-id/loan';
$options = array(
    'http' => array(
        'header'  => "Authorization: Bearer YOUR_API_KEY\r\n",
        'method'  => 'POST'
    )
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) {
    // Handle error
} else {
    $response = json_decode($result, true);
    print_r($response);
}
?>

Python
import requests
def verify_transaction():
    url = "https://api.banca.me/partner/pre-approve/your-transaction-id/loan"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY"
    }
    try:
        response = requests.post(url, headers=headers)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        raise

Example response:

{
  "data": {
    "loanAmount": 660000,
    "interestRate": 0.29,
    "periods": 2,
    "installmentAmount": 330000,
    "lastInstallmentAmount": 330000,
    "state": "ACTIVE",
    "transferDate": "2022-08-01",
    "externalTrxId": "your-transaction-id",
    "installments": [
      {
        "state": "ACTIVE",
        "period": 1,
        "expirationDate": "2022-09-01"
      },
      {
        "state": "ACTIVE",
        "period": 2,
        "expirationDate": "2022-10-01"
      }
    ]
  }
}

Quickstart: with pre-evaluation

Step 1: Get your API Keys

Step 2: Evaluate customer and get installment options

Step 3 (Optional): Determine user selected installment option

Step 4: Create a widgetToken

Step 5 - Initiate payment: Load the widget or redirect to payment URL

Step 6: Handle widget events

Step 7: Verify transaction through backend

Step 1: Get your API Keys​

Step 2: Evaluate customer and get installment options​

Step 3 (Optional): Determine user selected installment option​

Step 4: Create a widgetToken​

Step 5 - Initiate payment: Load the widget or redirect to payment URL​

Step 6: Handle widget events​

Step 7: Verify transaction through backend​

Step 1: Get your API Keys

Step 2: Evaluate customer and get installment options

Step 3 (Optional): Determine user selected installment option

Step 4: Create a widgetToken

Step 5 - Initiate payment: Load the widget or redirect to payment URL

Step 6: Handle widget events

Step 7: Verify transaction through backend