Skip to main content

Quickstart: without pre-evaluation

To start using banca.me buy now, pay later API, follow the following steps:

  1. Get your API keys
    API Keys

    You will need a set of API keys (both Private and Public) for each merchant that integrates with banca.me.

  2. Create a widget session through a widgetToken
  3. Initiate payment: Load the widget using the widgetToken or redirect to payment URL
  4. Handle post-payments events
  5. Verify transaction through backend or webhook
    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 appropriate API keys. For more details about authentication, check out the Authentication guide. There are two types of keys:

  1. Private Key (Backend): Used for backend API authentication. This key has full access to all API endpoints and should be kept secure. Never expose this key in client-side code or public repositories.
  2. Public Key (Frontend): Used for frontend widget initialization. This key has limited permissions and is safe to use in client-side code. It's required for initializing the Banca.me widget. Your API keys will be available to you through 1Password.

Step 2: 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:

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);

Example response:

{
  "data": {
    "accepted": true,
    "widgetToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
Widget Token is temporary

widgetToken is temporary and will expire in 10 minutes.

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

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.

Step 4: Handle widget events​

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 5: Verify transaction​

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 using your externalTrxId parameter. 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
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;
  }
}

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"
      }
    ]
  }
}