Skip to main content
POST
/
v1
/
issuing
/
cards
/
get
/
bins
Card BIN Query
curl --request POST \
  --url https://gate.dev.payloco.com/gateway/v1/issuing/cards/get/bins \
  --header 'Content-Type: application/json' \
  --header 'signature: <api-key>' \
  --data '
{
  "charset": "UTF-8",
  "version": "<string>",
  "transType": "PAY",
  "accessType": "s2s",
  "signType": "<string>",
  "memberId": "<string>",
  "merchantId": "<string>",
  "requestTime": "<string>",
  "cardFormFactor": "PHYSICAL",
  "cardType": "SINGLE",
  "cardScheme": "MasterCard",
  "cardCurrency": "USD"
}
'
{
  "success": true,
  "errCode": "<string>",
  "errMessage": "<string>",
  "status": "<string>",
  "traceId": "<string>",
  "data": {
    "cardBin": "<string>",
    "cardCurrency": "<string>",
    "cardScheme": "<string>",
    "cardType": "SINGLE",
    "cardFormFactor": "VIRTUAL",
    "billingAddressUpdatable": "Y",
    "expiryDateCustomization": "Y",
    "remainingAvailableCard": "<string>",
    "availableCard": "<string>"
  }
}

Authorizations

​
signature
string
header
required

Request Signing

Request signing is used to verify the integrity of messages between the platform and merchants. Signing occurs in two scenarios:

  1. The merchant server signs requests sent to the PayLoco open platform;
  2. The PayLoco platform signs asynchronous notifications sent to merchants. PayLoco requires RSA private key signing and RSA public key verification. Developers must use the merchant private key to sign outgoing requests (scenario 1) and the PayLoco public key to verify incoming notifications (scenario 2).

Signing rules:

  1. Sign request.body using the merchant private key (SHA256WithRSA: compute SHA-256 hash, then RSA-encrypt with private key to produce the digital signature);
Signature signature = Signature.getInstance("SHA256withRSA");
signature.initSign(privateKey);
// When computing SHA256withRSA, convert byte stream with UTF-8 encoding to avoid incorrect signatures for Chinese parameters
signature.update(request.body);
byte[] signedHash = signature.sign();
  1. Base64-encode the signed result;
String signature = Base64.getEncoder().encodeToString(signedHash);
  1. Place the encoded value in the signature request header. Note: signing applies to request.body. When request.body is empty (e.g. query requests), no signature is required.

Body

application/json
​
charset
string
default:UTF-8
required

Data encoding [utf-8]

Example:

"UTF-8"

​
version
string
required

API version. Current version is 2.0.0. Must be 2.0.0.

Example:

"2.0.0"

​
transType
enum<string>
default:PAY
required

Transaction Type

  • Use PAY for payment transactions
  • Use VCC for VCC card transactions
Available options:
PAY,
CREDIT_CARD,
3D_PREAUTH_VOIDS,
3D_PREAUTH_COMPLETION,
REFUND,
VOIDS,
QUERY,
TRANSFER,
DOWNLOAD,
REGISTRATION,
FILEUPLOAD,
INQUIRYREGISTRATIONSTATUS,
AUTHORIZE,
VCC
​
accessType
string
default:s2s
required

API access type

Example:

"s2s"

​
signType
string
required

Message signature type

Example:

"RSA"

​
memberId
string
required

Institution ID

Example:

"2023010558663764"

​
merchantId
string
required

Merchant ID

Example:

"2023010558663764"

​
requestTime
string
required

Request time in RFC3339 format: yyyy-MM-ddTHH:mm:ss.SSSXXX. Must be within 2 minutes of current time.

Example:

"2024-05-24T14:29:32.682+08:00"

​
cardFormFactor
enum<string>
required

Card medium。

Available options:
PHYSICAL,
VIRTUAL
Example:

"VIRTUAL"

​
cardType
enum<string>
required

Card type

  • SINGLE - A single card only has prepaid mode.
  • SHARE - A share card can have debit mode, meaning it is associated with debit program and account.
Available options:
SINGLE,
SHARE
Example:

"SHARE"

​
cardScheme
enum<string>
required

Card network

Available options:
MasterCard,
VISA
Example:

"VISA"

​
cardCurrency
enum<string>
required

卡币种

Available options:
USD,
EUR,
GBP
Example:

"USD"

Response

200 - application/json

OK

​
success
boolean
required

Whether the request succeeded

​
errCode
string
required

Response status code. 00000000 means success; other codes indicate failure. See system error codes.

Example:

"00000003"

​
errMessage
string
required

Error message

Example:

"处理中"

​
status
string
required

Order status (see supplementary notes)

Example:

"PENDING"

​
traceId
string
required

Unique request trace ID. Provide this when reporting issues for troubleshooting.

Example:

"33fae7b7aed1233f"

​
data
object

Returned object