Colombia Transactions
PSE
PSE is a payment method that allows the customer to make almost instant payments in Colombia, directly from their bank account. Since the PSE has the payer information attached, some contact information fields will be needed and validated from the subject_id. You can check it in Required information for registration (Person) which information we ask for PSE payments.
Apart from the URL, other information related to the payment will also be present among the transaction data. You can use it to keep your customer informed of the payment information and references.
The whole process takes place on the same page. After sending the payload you will receive a URL with the payment link for the customer to pay with PSE. The steps for the payment after entering the link are listed below:
- In your checkout page, when the customer is trying to make a payment, a list of bank codes and names is retrieved and listed to the customer;
- The customer selects his bank code, and you'll send the payload for the PSE transaction to us. When the transaction is created, in the response a bank payment URL is presented;
- You'll share this URL with the customer, and he will be redirected to his/her bank website to make the payment; The link will work only once, for 21 minutes. If the customer visits and closes the window before completing the payment, another payment will need to be generated.
- The customer will authenticate the payment in their bank and proceed with the payment.
- Once the payment is made and confirmed by the customer, he will be automatically redirected to the specified URL in the transaction payload (your checkout page from the beginning). In up to 3 minutes, the
identifiedwebhook will also be received.
[You can also check this flow in this PDF Guide](/sample_docs/PSE Checkout Guide.pdf)
curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
-d '{
"transaction": {
"currency": "COP",
"exchange_currency": "USD",
"value": "850000.00",
"from_pse": {
"financial_institution_code": "1077",
"redirect_url": "your website callback page",
"payment_description": "Some description"
},
"to_bank_account_id": "COP/USD cash-in internal account id",
"subject_id": "Customer id"
}
}'
HTTP Request
POST /transactions
Body Parameters
| Parameter | Description | Type | Required |
|---|---|---|---|
transaction | An object containing all the required values | object | true |
currency | Source currency for the transaction (ISO 4217 format) | string | true |
exchange_currency | Currency to be exchanged (ISO 4217 format) | string | true |
value | Value to be exchanged (in the source currency) | string | true |
from_pse | An object, containing the following parameters: | object | true |
from_pse.financial_institution_code | Bank code obtained using the PSE banks endpoint. More info on this in the next section | string | true |
from_pse.redirect_url | The URL from your website/platform in which the customer will be redirected upon finishing payment | string | true |
from_pse.payment_description | Any description with up to 80 characters related to the payment. Will be displayed on the confirmation page and recorded among the transaction information | string | false |
to_bank_account_id | ID of the account you will send the funds after the PSE is paid | string | true |
subject_id | ID of your customer | string | true |
This subject must have the following attributes filled: address_street, address_number, phone_area_code, phone_number and email
*
Field Requirements
| Field | Requirements |
|---|---|
social_name | Maximum length of 64 characters |
address_street + address_number + address_complement + address_city | Maximum length of 64 characters |
email | Maximum length of 120 characters. Notice that this e-mail will receive receipts and OTP codes even in sandbox mode, so provide a valid e-mail address when testing |
phone_area_code | Maximum length of 3 characters |
phone_number | Maximum length of 7 characters |
PSE Error Handling
When a PSE transaction cannot be processed, the transaction is returned with status: "canceled" and a canceled_reason field describing the issue. Below are the possible error messages:
canceled_reason | Description |
|---|---|
Transaction amount exceeds maximum allowed for PSE | The value exceeds the maximum limit allowed by PSE for a single transaction. |
The transaction amount is in an invalid format or is zero. Expected format: up to 12 integer digits with exactly 2 decimal places (14 total significant digits; e.g. 50000.00). Please verify the value and try again. | The transaction value is zero or could not be processed. Ensure the value field is a valid positive number. |
The bank entity cannot be contacted to initiate this transaction. Choose another one or try again later. | The selected bank is temporarily unavailable. The customer should select a different bank or retry later. |
Unable to create the PSE. Try again later or contact the support. | A generic error occurred during PSE creation. Retry the transaction or contact Attrus support. |
PSE banks
This endpoint is used to get the list of supported bank institutions for PSE in Colombia. You'll need to request it once a week, as it is updated on this frequency, and you'll use the results to populate a dropdown list in the same order they are returned. Note that the list returned in the production environment may have slight differences from the one returned in the sandbox environment.
The first result in the list is always A continuación seleccione su banco, which is the only item that is not a bank. It should be used as a placeholder in your dropdown list.
curl -X GET "https://api.facilitapay.com/api/v1/bank_accounts/pse" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."
HTTP Request
GET /bank_accounts/pse
Payout (COP)
After registering your customer bank account with us, you will be able to pay them locally using the following endpoint. We will use the Bank details you registered with us.
The payout transactions can be initiated within your foreign currency cash-out account or your Colombian cash-out account.
*If you prefer to do a payout with the full value already in local currency, please refer to section Reverse Exchange of this documentation.
curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
-d '{
"transaction": {
"currency": "USD or COP",
"exchange_currency": "COP",
"value": "500.00",
"from_bank_account_id": "your USD/COP cash-out internal account id",
"to_bank_account_id": "the id of your customer bank account",
"subject_id": "your customer id"
}
}'
HTTP Request
POST /transactions
Body Parameters
| Parameter | Description | Type | Required |
|---|---|---|---|
transaction | An object containing all the required values | object | true |
currency | Currency of your internal bank account | string | true |
exchange_currency | For PSE, always use COP | string | true |
value | Amount to be sent to Attrus or deducted from an internal bank account balance | string | true |
from_bank_account_id | UUID of your internal bank account. Its currency must match the currency informed on the currency attribute | string | true |
to_bank_account_id | Destination bank account UUID. This bank account must be from your Colombian customer | string | true |
subject_id | UUID of your customer, i.e. the owner of the to_bank_account_id | string | true |
Payout Banks (COP)
This endpoint is used to get the list of supported bank institutions for payout COP in Colombia.
curl -X GET "https://api.facilitapay.com/api/v1/banks/cop" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...."
HTTP Request
GET /banks/cop