Resolve Bank Selection Before a Purchase

POST

payment

bank-options

Resolve bank-selection requirements before a bank-redirect purchase

curl --request POST \
  --url https://api.therius.io/v1/payment/bank-options \
  --header 'Content-Type: application/json' \
  --data '
{
  "key": "<string>",
  "paymentMethod": "<string>",
  "currency": "<string>",
  "amount": 123
}
'

import requests

url = "https://api.therius.io/v1/payment/bank-options"

payload = {
    "key": "<string>",
    "paymentMethod": "<string>",
    "currency": "<string>",
    "amount": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({key: '<string>', paymentMethod: '<string>', currency: '<string>', amount: 123})
};

fetch('https://api.therius.io/v1/payment/bank-options', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.therius.io/v1/payment/bank-options",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'key' => '<string>',
    'paymentMethod' => '<string>',
    'currency' => '<string>',
    'amount' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.therius.io/v1/payment/bank-options"

	payload := strings.NewReader("{\n  \"key\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"amount\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.therius.io/v1/payment/bank-options")
  .header("Content-Type", "application/json")
  .body("{\n  \"key\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"amount\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.therius.io/v1/payment/bank-options")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"key\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"amount\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "bankSelectionMode": "required",
  "connectionCode": "<string>",
  "banks": [
    {
      "code": "<string>",
      "name": "<string>"
    }
  ]
}

Some redirect-to-bank methods need the shopper’s bank chosen before you call POST /payment/purchase — the bank code has to be pinned to the exact connection it was resolved against, since a bank/issuer code is not a shared namespace across providers. POST /payment/bank-options runs routing ahead of time so your checkout UI knows whether (and how strongly) to render a bank picker.

Whatever connectionCode this endpoint returns must be echoed back on the actual purchase call, regardless of bankSelectionMode — this was empirically confirmed, not just theorized: PayU’s own PSE bank codes were cross-checked against an independent Colombia bank-code reference and several diverged outright. Routing to a different connection between this call and the purchase call would make the chosen bank code meaningless.

`bankSelectionMode`

Value	Meaning
`required`	The purchase call will fail without a chosen bank. Currently `pse` (via PayU) and `fpx` (via Adyen).
`optional`	A picker is available and skips the provider’s own hosted picker, but purchase works fine without one. Currently `ideal` (via Adyen) — omit the bank and Adyen shows its own bank-selection page instead.
`none`	Nothing to pick, or no bank list is available yet for this provider/method combination. Render no picker.

Coverage today is pse, fpx, and ideal only. Other bank-redirect methods return bankSelectionMode: "none" — this is not necessarily proof they never need one, only that Therius doesn’t source a bank list for them yet.

Check before rendering a picker

curl -X POST https://api.therius.io/v1/payment/bank-options \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "MERCHANT_001",
    "paymentMethod": "pse",
    "currency": "COP",
    "amount": 500000
  }'

{
  "bankSelectionMode": "required",
  "connectionCode": "conn_a1b2c3d4",
  "banks": [
    { "code": "1007", "name": "BANCOLOMBIA" },
    { "code": "1051", "name": "BANCO DAVIVIENDA" },
    { "code": "1023", "name": "BANCO DE OCCIDENTE" }
  ]
}

Use the result on the purchase call

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-001",
  "amount": { "currency": "COP", "value": 500000, "exponent": 2 },
  "connectionCode": "conn_a1b2c3d4",
  "paymentMethod": {
    "type": "pse",
    "pse": {
      "payerName": "Ada Lovelace",
      "issuerId": "1007",
      "payerTaxId": "1234567890"
    }
  }
}

The JS SDK’s Checkout Widget calls this automatically for pse, fpx, and ideal panels the first time they’re submitted, and caches both the result and the connectionCode per method — you don’t need to call it directly if you’re using the widget.

Body

application/json

key

string

required

Your merchant code.

paymentMethod

string

required

The APM method code to check, e.g. pse, fpx, ideal.

currency

string

required

amount

integer

required

Minor units.

Response

Bank selection requirements for this provider/method combination

bankSelectionMode

enum<string>

required: purchase will fail without a chosen bank (pse via PayU, fpx via Adyen). optional: a picker is available and skips the provider's own hosted picker, but purchase works fine without one (ideal via Adyen). none: nothing to pick, or no bank list is available yet for this provider/method.

Available options:

required,

optional,

none

connectionCode

string

Echo this back as connectionCode on the actual purchase call, regardless of bankSelectionMode -- bank/issuer codes are not a shared namespace across providers.

banks

object[]

Show child attributes

Resolve bank-selection requirements before a bank-redirect purchase

curl --request POST \
  --url https://api.therius.io/v1/payment/bank-options \
  --header 'Content-Type: application/json' \
  --data '
{
  "key": "<string>",
  "paymentMethod": "<string>",
  "currency": "<string>",
  "amount": 123
}
'

import requests

url = "https://api.therius.io/v1/payment/bank-options"

payload = {
    "key": "<string>",
    "paymentMethod": "<string>",
    "currency": "<string>",
    "amount": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({key: '<string>', paymentMethod: '<string>', currency: '<string>', amount: 123})
};

fetch('https://api.therius.io/v1/payment/bank-options', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.therius.io/v1/payment/bank-options",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'key' => '<string>',
    'paymentMethod' => '<string>',
    'currency' => '<string>',
    'amount' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.therius.io/v1/payment/bank-options"

	payload := strings.NewReader("{\n  \"key\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"amount\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.therius.io/v1/payment/bank-options")
  .header("Content-Type", "application/json")
  .body("{\n  \"key\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"amount\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.therius.io/v1/payment/bank-options")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"key\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"currency\": \"<string>\",\n  \"amount\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "bankSelectionMode": "required",
  "connectionCode": "<string>",
  "banks": [
    {
      "code": "<string>",
      "name": "<string>"
    }
  ]
}

Payments

Tokenization

Subscriptions

Subscription Plans

SDK Session

Resolve Bank Selection Before a Purchase

`bankSelectionMode`

Check before rendering a picker

Use the result on the purchase call

Body

Response

​bankSelectionMode

​Check before rendering a picker

​Use the result on the purchase call

Body

Response

`bankSelectionMode`

Check before rendering a picker

Use the result on the purchase call