Transactions¶
Sales, authorizations, completions, refunds, voids, tokens, and wallet payments.
Test endpoint to void a specific hardcoded refund (RefundId: 105452)¶
/api/Transactions
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Void Response | Response |
Example response
Close Preauthorization¶
/api/Transactions/ClosePreauth
Close a preauthorization request.
The Close Preauthorization Request is required to add a tip amount and close the Preauthorization Request.
Request body¶
Schema: ClosePreauthRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
AdditionalTip |
number (double) | Optional | Additional Tip Amount |
Amount |
number (double) | Required | Transaction Amount |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
CurrencyCode |
string | Optional | — |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
ServiceReferenceNumber |
string | Required | The transaction identifier provided by the Blackstone system at the time of the transaction. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for reference purposes only; must be unique. |
VerificationOverrides |
VerificationOverrides | Optional | Optional overrides for the merchant's CVV, zip code and address verifications applied to the completion response. Honored only for Rapid Connect; ignored for other processors. Country is not evaluated when closing a preauthorization. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/ClosePreauth' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"ServiceReferenceNumber": "<service-reference-number>",
"Amount": 10.0,
"UserTransactionNumber": "unique-transaction-id",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Preauthorization Response | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Close All Settled Transaction¶
/api/Transactions/DoCloseAllSettledTransaction
Request body¶
Schema: SettlementRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
UserName |
string | Required | User credential of the client on the host. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/DoCloseAllSettledTransaction' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Settlement Response | SettlementResponse |
Example response
Full Refund¶
/api/Transactions/DoFullRefund
Process a full refund. The request will refund the amount that can be refunded, taking into account any prior partial refunds, not to exceed the original transaction amount.
This request will refund all monies that can be refunded (original transaction amount minus any partial refunds previously processed), not to exceed the original transaction amount. Use DoRefundV2 and DoFullRefundV2 for explicit Rapid Connect capture behavior.
Request body¶
Schema: RefundRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Account |
string | Optional | Card number. Optional if using swipe method. Otherwise required. |
Amount |
number (double) | Required | Amount to be refunded. The amount to be refunded can be less than the original transaction amount.Multiple refunds can be applied to the same transaction as long as the total amount of all refunds does not exceed the original transaction amount. The API refunds this exact amount and does not automatically prorate a surcharge into a separate refund component. |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
ExpDate |
string | Optional | Card expiration date (MMYY). |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
KSN |
string | Optional | Key serial number of the PIN block for EBT returns. V2 refunds require 20 hexadecimal characters. |
Password |
string | Required | Password of the client on the host. |
PinBlock |
string | Optional | Encrypted PIN block for EBT returns. V2 refunds also accept online PIN for Debit and Credit EMV. |
SURI |
string | Optional | SURI number |
ServiceTransactionNumber |
string | Required | The transaction identifier provided by the Blackstone system at the time of the original transaction. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
TrackData |
string | Optional | Card track data. Optional if using the No Swipe method. |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for referencepurposes only; must be unique. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/DoFullRefund' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"ServiceTransactionNumber": "<service-transaction-number>",
"Amount": 10.0,
"UserTransactionNumber": "unique-transaction-id",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Sale | DoFullRefundResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"RefundedAmount": 10.0,
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0
}
Refund the remaining balance using the explicit Rapid Connect V2 contract.¶
/api/Transactions/DoFullRefundV2
The server computes Amount. Pending recovery preserves the originally reserved refund amount and reference.
Request body¶
Schema: RefundRequestV2
| Field | Type | Requirement | Description |
|---|---|---|---|
Account |
string | Optional | Card number. Optional if using swipe method. Otherwise required. |
Amount |
number (double) | Required | Amount to be refunded. The amount to be refunded can be less than the original transaction amount.Multiple refunds can be applied to the same transaction as long as the total amount of all refunds does not exceed the original transaction amount. The API refunds this exact amount and does not automatically prorate a surcharge into a separate refund component. |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
EmvData |
string | Optional | Card-present refund (Rapid Connect): EMV TLV data (hex) read by the terminal for this refund. It must contain 9C=20 (refund). When present, 9F02 must equal Amount in minor units and 5F2A the currency of the original sale. |
ExpDate |
string | Optional | Card expiration date (MMYY). |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
KSN |
string | Optional | Key serial number of the PIN block for EBT returns. V2 refunds require 20 hexadecimal characters. |
Password |
string | Required | Password of the client on the host. |
PinBlock |
string | Optional | Encrypted PIN block for EBT returns. V2 refunds also accept online PIN for Debit and Credit EMV. |
PosEntryMode |
string — KeyEntered, AmexContactless, CredentialOnFile, Contactless, Swiped, AmexDigitalWallet, Chip, ChipFallbackSwipe, ChipFallbackManual |
Optional | Card-present refund (Rapid Connect): how the card was read for this refund. Allowed values: Chip, Contactless, Swiped, ChipFallbackSwipe, AmexContactless. Required in card-present mode. |
SURI |
string | Optional | SURI number |
ServiceTransactionNumber |
string | Required | The transaction identifier provided by the Blackstone system at the time of the original transaction. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
TerminalEntryCapability |
string — Unspecified, NotUsed, MagneticStripeOnly, MagneticStripeAndKeyEntry, MagneticStripeKeyEntryAndChip, Barcode, ContactlessChip, Ocr, ChipOnly, ChipAndMagneticStripe, ManualEntryOnly, ContactlessMagneticStripe, Hybrid, DoesNotReadCardData |
Optional | Card-present refund (Rapid Connect): optional card entry capability of the terminal (Rapid Connect TermEntryCapablt): what the device can read, not how this card was read. Send Hybrid (12) from a terminal with magnetic stripe, chip and contactless readers. When EmvData is present it must be MagneticStripeKeyEntryAndChip, ContactlessChip, ChipOnly, ChipAndMagneticStripe or Hybrid. When omitted, Rapid Connect infers it from PosEntryMode. |
Track2 |
string | Optional | Card-present refund (Rapid Connect): Track 2 data read by the terminal for this refund (swiped, chip fallback swipe or contactless MSD). Any supplied capture field must be valid; empty or whitespace values are rejected. A Debit refund needs track 2 data: this field (or TrackData) or EMV tag 57 in EmvData. |
TrackData |
string | Optional | Card track data. Optional if using the No Swipe method. |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for referencepurposes only; must be unique. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/DoFullRefundV2' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Amount": 10.0,
"UserTransactionNumber": "unique-transaction-id",
"ServiceTransactionNumber": "<service-transaction-number>",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Sale | DoFullRefundResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"RefundedAmount": 10.0,
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0
}
Refund¶
/api/Transactions/DoRefund
Process a refund. The request will fail if the transaction was previously fully refunded or voided. Amount may be partial or full, is applied exactly as sent, and does not trigger automatic surcharge proration. Every refund operation requires a new unique UserTransactionNumber; ServiceTransactionNumber identifies the original transaction. Use DoRefundV2 and DoFullRefundV2 for explicit Rapid Connect capture behavior.
Request body¶
Schema: RefundRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Account |
string | Optional | Card number. Optional if using swipe method. Otherwise required. |
Amount |
number (double) | Required | Amount to be refunded. The amount to be refunded can be less than the original transaction amount.Multiple refunds can be applied to the same transaction as long as the total amount of all refunds does not exceed the original transaction amount. The API refunds this exact amount and does not automatically prorate a surcharge into a separate refund component. |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
ExpDate |
string | Optional | Card expiration date (MMYY). |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
KSN |
string | Optional | Key serial number of the PIN block for EBT returns. V2 refunds require 20 hexadecimal characters. |
Password |
string | Required | Password of the client on the host. |
PinBlock |
string | Optional | Encrypted PIN block for EBT returns. V2 refunds also accept online PIN for Debit and Credit EMV. |
SURI |
string | Optional | SURI number |
ServiceTransactionNumber |
string | Required | The transaction identifier provided by the Blackstone system at the time of the original transaction. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
TrackData |
string | Optional | Card track data. Optional if using the No Swipe method. |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for referencepurposes only; must be unique. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/DoRefund' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"ServiceTransactionNumber": "<service-transaction-number>",
"Amount": 10.0,
"UserTransactionNumber": "unique-transaction-id",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Refund Response. ResponseCode 200, 6, 205 or 506 (see remarks). | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Refund using the explicit Rapid Connect V2 contract.¶
/api/Transactions/DoRefundV2
Fresh capture fields are validated before reserving the reference. Pending retries never replay a financial call.
Request body¶
Schema: RefundRequestV2
| Field | Type | Requirement | Description |
|---|---|---|---|
Account |
string | Optional | Card number. Optional if using swipe method. Otherwise required. |
Amount |
number (double) | Required | Amount to be refunded. The amount to be refunded can be less than the original transaction amount.Multiple refunds can be applied to the same transaction as long as the total amount of all refunds does not exceed the original transaction amount. The API refunds this exact amount and does not automatically prorate a surcharge into a separate refund component. |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
EmvData |
string | Optional | Card-present refund (Rapid Connect): EMV TLV data (hex) read by the terminal for this refund. It must contain 9C=20 (refund). When present, 9F02 must equal Amount in minor units and 5F2A the currency of the original sale. |
ExpDate |
string | Optional | Card expiration date (MMYY). |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
KSN |
string | Optional | Key serial number of the PIN block for EBT returns. V2 refunds require 20 hexadecimal characters. |
Password |
string | Required | Password of the client on the host. |
PinBlock |
string | Optional | Encrypted PIN block for EBT returns. V2 refunds also accept online PIN for Debit and Credit EMV. |
PosEntryMode |
string — KeyEntered, AmexContactless, CredentialOnFile, Contactless, Swiped, AmexDigitalWallet, Chip, ChipFallbackSwipe, ChipFallbackManual |
Optional | Card-present refund (Rapid Connect): how the card was read for this refund. Allowed values: Chip, Contactless, Swiped, ChipFallbackSwipe, AmexContactless. Required in card-present mode. |
SURI |
string | Optional | SURI number |
ServiceTransactionNumber |
string | Required | The transaction identifier provided by the Blackstone system at the time of the original transaction. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
TerminalEntryCapability |
string — Unspecified, NotUsed, MagneticStripeOnly, MagneticStripeAndKeyEntry, MagneticStripeKeyEntryAndChip, Barcode, ContactlessChip, Ocr, ChipOnly, ChipAndMagneticStripe, ManualEntryOnly, ContactlessMagneticStripe, Hybrid, DoesNotReadCardData |
Optional | Card-present refund (Rapid Connect): optional card entry capability of the terminal (Rapid Connect TermEntryCapablt): what the device can read, not how this card was read. Send Hybrid (12) from a terminal with magnetic stripe, chip and contactless readers. When EmvData is present it must be MagneticStripeKeyEntryAndChip, ContactlessChip, ChipOnly, ChipAndMagneticStripe or Hybrid. When omitted, Rapid Connect infers it from PosEntryMode. |
Track2 |
string | Optional | Card-present refund (Rapid Connect): Track 2 data read by the terminal for this refund (swiped, chip fallback swipe or contactless MSD). Any supplied capture field must be valid; empty or whitespace values are rejected. A Debit refund needs track 2 data: this field (or TrackData) or EMV tag 57 in EmvData. |
TrackData |
string | Optional | Card track data. Optional if using the No Swipe method. |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for referencepurposes only; must be unique. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/DoRefundV2' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Amount": 10.0,
"UserTransactionNumber": "unique-transaction-id",
"ServiceTransactionNumber": "<service-transaction-number>",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | OK | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Reversal¶
/api/Transactions/DoReversal
Uses the legacy reversal contract. Use DoReversalV2 for explicit Rapid Connect reversal and refund capture.
Request body¶
Schema: ReversalRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The user transaction number that was sent by the client at the time of the transaction. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/DoReversal' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"UserTransactionNumber": "unique-transaction-id",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Reversal Response. ResponseCode 200, 6, 205 or 506 (see remarks). | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Reverse a Rapid Connect sale using the explicit V2 contract.¶
/api/Transactions/DoReversalV2
Uses verified sale context and optional fresh reversal or refund capture. Legacy reversals keep the original action.
Request body¶
Schema: ReversalRequestV2
| Field | Type | Requirement | Description |
|---|---|---|---|
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
EmvData |
string | Optional | Rapid Connect EMV full reversal: EMV TLV data (hex) read by the terminal for this reversal. Required to void an open EMV sale; it must not contain 9C=20 and must not be sent for a non-EMV sale. Unless the sale returned a TransArmor token that is stored, the card number in tag 5A or 57 is the void credential: without it (or with 5A and 57 that disagree) the sale is not voided but refunded (with RefundData, or by token). A supplied empty or whitespace value is rejected with 506. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
RefundData |
RefundCaptureData | Optional | Rapid Connect: fresh card-present refund capture, used when the sale cannot be voided (settled sale, void window elapsed, Debit voids disabled, or the host requires a refund). Its 9F02 must equal the full refundable amount of the sale. Required for Debit sales that are refunded. An empty non-null object is an incomplete capture and is rejected with 506 rather than treated as absent. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The user transaction number that was sent by the client at the time of the transaction. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/DoReversalV2' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"UserTransactionNumber": "unique-transaction-id",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | OK | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Settlement¶
/api/Transactions/DoSettlement
Request a settlement of all outstanding transactions for a merchant.
Request body¶
Schema: SettlementRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
UserName |
string | Required | User credential of the client on the host. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/DoSettlement' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Settlement Response | SettlementResponse |
Example response
Void¶
/api/Transactions/DoVoid
Void a transaction. The request will fail if the transaction was previously voided or refunded.
An open Rapid Connect sale with a pending card-present refund or reversal answers 205 (outcome pending; the pending reference is in Msg): reconcile that operation before voiding.
Request body¶
Schema: VoidRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
ServiceTransactionNumber |
string | Required | The transaction identifier used for reference purposes only; must be unique. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier provided by the Blackstone system at the time of the transaction. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/DoVoid' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"UserTransactionNumber": "unique-transaction-id",
"ServiceTransactionNumber": "<service-transaction-number>",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Void Response | Response |
Example response
Force Retail Sale¶
/api/Transactions/ForceRetailSale
Request body¶
Schema: ForceRetailSaleRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Amount |
number (double) | Required | Transaction amount as a JSON number. Quoted numeric strings are not part of the public contract. |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
ApprovalCode |
string | Optional | The approval code received from the bank |
AuthNumber |
integer (int32) | Optional | Auth Number. |
CVN |
string | Optional | Credit card verification number (security code). Not required if credit card is swiped. |
CardDifferenceAmount |
number (double) | Optional | The amount dedicated to the card difference (this is an optional charge passed on to the user) |
CardNumber |
string | Optional | Credit card number. Not required if credit card isswiped. |
CurrencyCode |
string | Optional | The Code of the currency to process the transaction. By default, USD dollar is used. |
CustomerAddress |
string | Optional | Optional address for the customer |
CustomerCity |
string | Optional | Optional city for the customer |
CustomerCountry |
string | Optional | Optional country for the customer |
CustomerEmail |
string | Optional | The email for the customer in the e-commerce transaction (optional) |
CustomerId |
integer (int32) | Optional | The merchant customer ID as a JSON integer. Quoted strings are not part of the public contract. |
CustomerPhone |
string | Optional | The phone number for the customer in the e-commerce transaction (optional) |
CustomerState |
string | Optional | Optional state for the customer |
DigWltProgType |
string | Optional | — |
DigWltToken |
string | Optional | — |
EmvData |
string | Optional | Contactless data. |
EnableCreditOnlinePin |
boolean | Optional | Enables online PIN only for ordinary Credit EMV sales on Rapid Connect with configured DUKPT. Defaults to false; Credit sales ignore residual PinBlock and KSN unless enabled. |
ExpDate |
string | Optional | Credit card expiration date. SaleWithToken accepts MMYY or MM/YY; other sale flows require MMYY. Not required if credit card is swiped. Rapid Connect token sales use the valid stored token expiration when available and otherwise require this field. |
ForceDuplication |
boolean | Optional | Indicates whether the payment should be executed even if a recent payment exists with the same signature. |
InvoiceNumber |
string | Optional | Optional invoice number associated with the transaction. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
KSN |
string | Optional | Optional DUKPT key serial number for the encrypted online PIN block. |
NameOnCard |
string | Optional | Cardholder Name. Not required if credit card is swiped. |
OrderReference |
string | Optional | Optional reference for the order in case it applies |
Password |
string | Required | Password of the client on the host. |
PaymentLinkId |
string | Optional | Optional Payment Link identifier when the transaction is paid from a payment link. |
PinBlock |
string | Optional | Optional encrypted online PIN block for Credit EMV. Supply together with KSN. |
PosCode |
string — ECommerce, Moto, RecurringBilling, Retail |
Optional | The condition in which the payment was captured |
PosEntryMode |
string — KeyEntered, AmexContactless, CredentialOnFile, Contactless, Swiped, AmexDigitalWallet, Chip, ChipFallbackSwipe, ChipFallbackManual |
Optional | The entry mode in which the payment was captured |
PurchaseCardLevel2 |
PurchaseCardLevel2Data | Optional | Optional Purchase Card Level 2 data sent to Rapid Connect for commercial card processing. |
SURI |
string | Optional | SURI number |
SaveCustomer |
boolean | Optional | This optional parameter indicates if the merchant wants to save the customer |
SaveToken |
boolean | Optional | Indicates to return a token for the card in case the transaction was successful |
SecureData |
string | Optional | The 3D secure data present once the 3D secure flow has been triggered for the transaction |
SecureTransactionId |
string | Optional | ID of the secure transaction |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
Street |
string | Optional | Cardholder�s billing street. Not required if credit card is swiped. |
SurchargeAmount |
number (double) | Optional | Optional surcharge amount as a JSON number. Direct API callers calculate and supply this value; the API does not derive it from the merchant's configured surcharge percentage. |
TaxAmount |
number (double) | Optional | The amount dedicated to the tax (this is an optional charge configurable by the merchant) |
TerminalEntryCapability |
string — Unspecified, NotUsed, MagneticStripeOnly, MagneticStripeAndKeyEntry, MagneticStripeKeyEntryAndChip, Barcode, ContactlessChip, Ocr, ChipOnly, ChipAndMagneticStripe, ManualEntryOnly, ContactlessMagneticStripe, Hybrid, DoesNotReadCardData |
Optional | Optional card entry capability of the terminal (Rapid Connect TermEntryCapablt): what the device can read, not how this card was read. Send Hybrid (12) from a terminal with magnetic stripe, chip and contactless readers. When EmvData is present it must be MagneticStripeKeyEntryAndChip, ContactlessChip, ChipOnly, ChipAndMagneticStripe or Hybrid. When omitted, Rapid Connect infers it from the entry mode. |
TipAmount |
number (double) | Optional | The amount dedicated to the tip (this is an optional charge for the client with a default value configurable by the merchant) |
Track2 |
string | Optional | Credit card track data. Not required if using the No Swipe method. |
TransactionType |
integer (int32) | Required | Transaction Type | Name | Value | Description | |---|---|---| | CREDIT | 1 | Credit transaction | | CREDIT_WITH_TOKEN | 2 | Credit with token transaction | | Pre_Authorization | 3 | Credit preauthorization request | | Pre_Authorization_Completion | 4 | Credit preauthorization completion | | SaleDebit | 5 | Debit Card Sale transaction | | EBT | 6 | EBT Transaction | | GIFTCARD | 7 | Blackstone Gift Card transaction | |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for reference purposes only; must be unique. |
VerificationOverrides |
VerificationOverrides | Optional | Optional per-transaction overrides for the merchant's CVV, zip code, address and country verifications. Honored only for Rapid Connect; ignored for other processors. |
ZipCode |
string | Optional | Cardholder�s zip code. Not required if credit card is swiped. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/ForceRetailSale' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Amount": 10.0,
"UserTransactionNumber": "unique-transaction-id",
"TransactionType": 1,
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Force Retail Sale Response | ForceRetailSaleResponse |
Example response
{
"AcsUrl": "<acs-url>",
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardType": "<card-type>",
"Is3DSecureNeeded": false,
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"avs": "<avs>",
"cv": "<cv>",
"displayMessage": "<display-message>",
"msoft_code": "<msoft-code>",
"phard_code": "<phard-code>"
}
Get Card PAN¶
/api/Transactions/GetCardPAN
Request body¶
Schema: GetCardPANRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
Token |
string | Optional | — |
UserName |
string | Required | User credential of the client on the host. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | OK | GetCardPANResponse |
Example response
Get Supported Currencies¶
/api/Transactions/GetSupportedCurrencies
Request body¶
Schema: SupportedCurrenciesRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
CurrencyCode |
string | Optional | — |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
UserName |
string | Required | User credential of the client on the host. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/GetSupportedCurrencies' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Get Supported Currencies Response | SupportedCurrenciesResponse |
Example response
Get Transaction¶
/api/Transactions/GetTransaction
Searches by the original UserTransactionNumber supplied by the integrator when the transaction was created. ServiceReferenceNumber and ServiceTransactionNumber are not accepted as substitutes.
Request body¶
Schema: GetTransactionRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The original UserTransactionNumber supplied by the integrator when the transaction was created. This endpoint does not search by ServiceReferenceNumber or ServiceTransactionNumber. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/GetTransaction' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"UserTransactionNumber": "unique-transaction-id",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Get Transaction Response | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Process Preauthorization¶
/api/Transactions/ProcessPreauth
Process a preauthorization for a sale transaction with tips.Requires a Close Preauthorization request to close the receipt even when the tip amount is zero.
A Preauthorization Request is required for sale transactions that include tips, whether the tip is added during or after checkout, as in restaurants or hair salons.The Preauthorization Request is processed with the sale amount (not including the tip amount). A Close Preauthorization Request must be processed to add the tip amount and close the receipt.This will complete the transaction.
IMPORTANT: Preauthorization requests must be closed within 30 days, even if the tip amount is zero. If a Preauthorization Request is not closed, the preauthorization amount is returned to the cardholder.
Request body¶
Schema: ProcessPreauthRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Account |
string | Optional | Credit card number |
Amount |
number (double) | Required | Preauthorization amount |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
CurrencyCode |
string | Optional | — |
IpAddress |
string | Optional | The client's IP address. |
IsClosable |
boolean | Required | Must be �True� to be able to close the preauthorization request. |
IsTest |
boolean | Optional | True if is a test sale |
NameOnCard |
string | Optional | Cardholder name as it appears on the credit card |
Password |
string | Required | Password of the client on the host. |
PosCode |
string — ECommerce, Moto, RecurringBilling, Retail |
Optional | The condition in which the payment was captured |
PurchaseCardLevel2 |
PurchaseCardLevel2Data | Optional | Optional Purchase Card Level 2 data persisted with the preauthorization. |
SecureData |
string | Optional | The 3D secure data present once the 3D secure flow has been triggered for the transaction |
SecureTransactionId |
string | Optional | — |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
Street |
string | Optional | Cardholder street address |
TrackData |
string | Optional | — |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for reference purposes only; must be unique. |
VerificationOverrides |
VerificationOverrides | Optional | Optional per-transaction overrides for the merchant's CVV, zip code, address and country verifications. Honored only for Rapid Connect; ignored for other processors. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
comments |
string | Optional | Comments |
cv |
string | Optional | Card Verification |
expDate |
string | Optional | Credit card expiration date (MMYY) |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
zipCode |
string | Optional | Cardholder zip code |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/ProcessPreauth' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Amount": 10.0,
"IsClosable": false,
"UserTransactionNumber": "unique-transaction-id",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Rpocess Rpeauthorization Response | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Process Preauthorization¶
/api/Transactions/ProcessPreauthWithToken
Process a preauthorization for a sale transaction with tips.Requires a Close Preauthorization request to close the receipt even when the tip amount is zero.
A Preauthorization Request is required for sale transactions that include tips, whether the tip is added during or after checkout, as in restaurants or hair salons.The Preauthorization Request is processed with the sale amount (not including the tip amount). A Close Preauthorization Request must be processed to add the tip amount and close the receipt.This will complete the transaction.
IMPORTANT: Preauthorization requests must be closed within 30 days, even if the tip amount is zero. If a Preauthorization Request is not closed, the preauthorization amount is returned to the cardholder.
Request body¶
Schema: ProcessPreauthWithTokenRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Account |
string | Optional | Credit card number |
Amount |
number (double) | Required | Preauthorization amount |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
CurrencyCode |
string | Optional | — |
IpAddress |
string | Optional | The client's IP address. |
IsClosable |
boolean | Required | Must be �True� to be able to close the preauthorization request. |
IsTest |
boolean | Optional | True if is a test sale |
NameOnCard |
string | Optional | Cardholder name as it appears on the credit card |
Password |
string | Required | Password of the client on the host. |
PosCode |
string — ECommerce, Moto, RecurringBilling, Retail |
Optional | The condition in which the payment was captured |
PurchaseCardLevel2 |
PurchaseCardLevel2Data | Optional | Optional Purchase Card Level 2 data persisted with the preauthorization. |
SecureData |
string | Optional | The 3D secure data present once the 3D secure flow has been triggered for the transaction |
SecureTransactionId |
string | Optional | — |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
Street |
string | Optional | Cardholder street address |
Token |
string | Optional | Token. |
TrackData |
string | Optional | — |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for reference purposes only; must be unique. |
VerificationOverrides |
VerificationOverrides | Optional | Optional per-transaction overrides for the merchant's CVV, zip code, address and country verifications. Honored only for Rapid Connect; ignored for other processors. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
comments |
string | Optional | Comments |
cv |
string | Optional | Card Verification |
expDate |
string | Optional | Credit card expiration date (MMYY) |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
zipCode |
string | Optional | Cardholder zip code |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/ProcessPreauthWithToken' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Amount": 10.0,
"IsClosable": false,
"UserTransactionNumber": "unique-transaction-id",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Rpocess Rpeauthorization Response | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Recurring Sale¶
/api/Transactions/RecurringSale
Request body¶
Schema: SaleRecurringRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Amount |
number (double) | Required | Transaction amount as a JSON number. Quoted numeric strings are not part of the public contract. |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
CVN |
string | Optional | Credit card verification number (security code). Not required if credit card is swiped. |
CardDifferenceAmount |
number (double) | Optional | The amount dedicated to the card difference (this is an optional charge passed on to the user) |
CardNumber |
string | Optional | Credit card number. Not required if credit card isswiped. |
Comments |
string | Optional | Transaction comments |
CurrencyCode |
string | Optional | The Code of the currency to process the transaction. By default, USD dollar is used. |
CustomerAddress |
string | Optional | Optional address for the customer |
CustomerCity |
string | Optional | Optional city for the customer |
CustomerCountry |
string | Optional | Optional country for the customer |
CustomerEmail |
string | Optional | The email for the customer in the e-commerce transaction (optional) |
CustomerId |
integer (int32) | Optional | The merchant customer ID as a JSON integer. Quoted strings are not part of the public contract. |
CustomerPhone |
string | Optional | The phone number for the customer in the e-commerce transaction (optional) |
CustomerState |
string | Optional | Optional state for the customer |
DigWltProgType |
string | Optional | — |
DigWltToken |
string | Optional | — |
EmvData |
string | Optional | Contactless data. |
EnableCreditOnlinePin |
boolean | Optional | Enables online PIN only for ordinary Credit EMV sales on Rapid Connect with configured DUKPT. Defaults to false; Credit sales ignore residual PinBlock and KSN unless enabled. |
ExpDate |
string | Optional | Credit card expiration date. SaleWithToken accepts MMYY or MM/YY; other sale flows require MMYY. Not required if credit card is swiped. Rapid Connect token sales use the valid stored token expiration when available and otherwise require this field. |
ForceDuplication |
boolean | Optional | Indicates whether the payment should be executed even if a recent payment exists with the same signature. |
Frecuency |
string — Daily, Weekly, Biweekl, Monthly, Quarterly, Biannually, Annually, Unscheduled |
Optional | Frecuency of recurring |
InvoiceNumber |
string | Optional | Optional invoice number associated with the transaction. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
KSN |
string | Optional | Optional DUKPT key serial number for the encrypted online PIN block. |
NameOnCard |
string | Optional | Cardholder Name. Not required if credit card is swiped. |
OrderReference |
string | Optional | Optional reference for the order in case it applies |
Password |
string | Required | Password of the client on the host. |
PaymentLinkId |
string | Optional | Optional Payment Link identifier when the transaction is paid from a payment link. |
PinBlock |
string | Optional | Optional encrypted online PIN block for Credit EMV. Supply together with KSN. |
PosCode |
string — ECommerce, Moto, RecurringBilling, Retail |
Optional | The condition in which the payment was captured |
PosEntryMode |
string — KeyEntered, AmexContactless, CredentialOnFile, Contactless, Swiped, AmexDigitalWallet, Chip, ChipFallbackSwipe, ChipFallbackManual |
Optional | The entry mode in which the payment was captured |
PurchaseCardLevel2 |
PurchaseCardLevel2Data | Optional | Optional Purchase Card Level 2 data sent to Rapid Connect for commercial card processing. |
SURI |
string | Optional | SURI number |
SaveCustomer |
boolean | Optional | This optional parameter indicates if the merchant wants to save the customer |
SaveToken |
boolean | Optional | Indicates to return a token for the card in case the transaction was successful |
SecureData |
string | Optional | The 3D secure data present once the 3D secure flow has been triggered for the transaction |
SecureTransactionId |
string | Optional | ID of the secure transaction |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
Street |
string | Optional | Cardholder�s billing street. Not required if credit card is swiped. |
SurchargeAmount |
number (double) | Optional | Optional surcharge amount as a JSON number. Direct API callers calculate and supply this value; the API does not derive it from the merchant's configured surcharge percentage. |
TaxAmount |
number (double) | Optional | The amount dedicated to the tax (this is an optional charge configurable by the merchant) |
TerminalEntryCapability |
string — Unspecified, NotUsed, MagneticStripeOnly, MagneticStripeAndKeyEntry, MagneticStripeKeyEntryAndChip, Barcode, ContactlessChip, Ocr, ChipOnly, ChipAndMagneticStripe, ManualEntryOnly, ContactlessMagneticStripe, Hybrid, DoesNotReadCardData |
Optional | Optional card entry capability of the terminal (Rapid Connect TermEntryCapablt): what the device can read, not how this card was read. Send Hybrid (12) from a terminal with magnetic stripe, chip and contactless readers. When EmvData is present it must be MagneticStripeKeyEntryAndChip, ContactlessChip, ChipOnly, ChipAndMagneticStripe or Hybrid. When omitted, Rapid Connect infers it from the entry mode. |
TipAmount |
number (double) | Optional | The amount dedicated to the tip (this is an optional charge for the client with a default value configurable by the merchant) |
Token |
string | Optional | The Token which identifies the credit card information. |
Track2 |
string | Optional | Credit card track data. Not required if using the No Swipe method. |
TransactionType |
integer (int32) | Required | Transaction Type | Name | Value | Description | |---|---|---| | CREDIT | 1 | Credit transaction | | CREDIT_WITH_TOKEN | 2 | Credit with token transaction | | Pre_Authorization | 3 | Credit preauthorization request | | Pre_Authorization_Completion | 4 | Credit preauthorization completion | | SaleDebit | 5 | Debit Card Sale transaction | | EBT | 6 | EBT Transaction | | GIFTCARD | 7 | Blackstone Gift Card transaction | |
Type |
string — Registration, Subsequent |
Optional | Type of recurring |
UniqueId |
string | Optional | Unique id of recurring |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for reference purposes only; must be unique. |
VerificationOverrides |
VerificationOverrides | Optional | Optional per-transaction overrides for the merchant's CVV, zip code, address and country verifications. Honored only for Rapid Connect; ignored for other processors. |
ZipCode |
string | Optional | Cardholder�s zip code. Not required if credit card is swiped. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/RecurringSale' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Amount": 10.0,
"UserTransactionNumber": "unique-transaction-id",
"TransactionType": 1,
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Sale Response | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Sale¶
/api/Transactions/Sale
Process a credit card sale transaction where sales do not include tips.Refer to Preauthorization Request when sales include tips.
Request body¶
Schema: SaleRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Amount |
number (double) | Required | Transaction amount as a JSON number. Quoted numeric strings are not part of the public contract. |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
CVN |
string | Optional | Credit card verification number (security code). Not required if credit card is swiped. |
CardDifferenceAmount |
number (double) | Optional | The amount dedicated to the card difference (this is an optional charge passed on to the user) |
CardNumber |
string | Optional | Credit card number. Not required if credit card isswiped. |
CurrencyCode |
string | Optional | The Code of the currency to process the transaction. By default, USD dollar is used. |
CustomerAddress |
string | Optional | Optional address for the customer |
CustomerCity |
string | Optional | Optional city for the customer |
CustomerCountry |
string | Optional | Optional country for the customer |
CustomerEmail |
string | Optional | The email for the customer in the e-commerce transaction (optional) |
CustomerId |
integer (int32) | Optional | The merchant customer ID as a JSON integer. Quoted strings are not part of the public contract. |
CustomerPhone |
string | Optional | The phone number for the customer in the e-commerce transaction (optional) |
CustomerState |
string | Optional | Optional state for the customer |
DigWltProgType |
string | Optional | — |
DigWltToken |
string | Optional | — |
EmvData |
string | Optional | Contactless data. |
EnableCreditOnlinePin |
boolean | Optional | Enables online PIN only for ordinary Credit EMV sales on Rapid Connect with configured DUKPT. Defaults to false; Credit sales ignore residual PinBlock and KSN unless enabled. |
ExpDate |
string | Optional | Credit card expiration date. SaleWithToken accepts MMYY or MM/YY; other sale flows require MMYY. Not required if credit card is swiped. Rapid Connect token sales use the valid stored token expiration when available and otherwise require this field. |
ForceDuplication |
boolean | Optional | Indicates whether the payment should be executed even if a recent payment exists with the same signature. |
InvoiceNumber |
string | Optional | Optional invoice number associated with the transaction. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
KSN |
string | Optional | Optional DUKPT key serial number for the encrypted online PIN block. |
NameOnCard |
string | Optional | Cardholder Name. Not required if credit card is swiped. |
OrderReference |
string | Optional | Optional reference for the order in case it applies |
Password |
string | Required | Password of the client on the host. |
PaymentLinkId |
string | Optional | Optional Payment Link identifier when the transaction is paid from a payment link. |
PinBlock |
string | Optional | Optional encrypted online PIN block for Credit EMV. Supply together with KSN. |
PosCode |
string — ECommerce, Moto, RecurringBilling, Retail |
Optional | The condition in which the payment was captured |
PosEntryMode |
string — KeyEntered, AmexContactless, CredentialOnFile, Contactless, Swiped, AmexDigitalWallet, Chip, ChipFallbackSwipe, ChipFallbackManual |
Optional | The entry mode in which the payment was captured |
PurchaseCardLevel2 |
PurchaseCardLevel2Data | Optional | Optional Purchase Card Level 2 data sent to Rapid Connect for commercial card processing. |
SURI |
string | Optional | SURI number |
SaveCustomer |
boolean | Optional | This optional parameter indicates if the merchant wants to save the customer |
SaveToken |
boolean | Optional | Indicates to return a token for the card in case the transaction was successful |
SecureData |
string | Optional | The 3D secure data present once the 3D secure flow has been triggered for the transaction |
SecureTransactionId |
string | Optional | ID of the secure transaction |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
Street |
string | Optional | Cardholder�s billing street. Not required if credit card is swiped. |
SurchargeAmount |
number (double) | Optional | Optional surcharge amount as a JSON number. Direct API callers calculate and supply this value; the API does not derive it from the merchant's configured surcharge percentage. |
TaxAmount |
number (double) | Optional | The amount dedicated to the tax (this is an optional charge configurable by the merchant) |
TerminalEntryCapability |
string — Unspecified, NotUsed, MagneticStripeOnly, MagneticStripeAndKeyEntry, MagneticStripeKeyEntryAndChip, Barcode, ContactlessChip, Ocr, ChipOnly, ChipAndMagneticStripe, ManualEntryOnly, ContactlessMagneticStripe, Hybrid, DoesNotReadCardData |
Optional | Optional card entry capability of the terminal (Rapid Connect TermEntryCapablt): what the device can read, not how this card was read. Send Hybrid (12) from a terminal with magnetic stripe, chip and contactless readers. When EmvData is present it must be MagneticStripeKeyEntryAndChip, ContactlessChip, ChipOnly, ChipAndMagneticStripe or Hybrid. When omitted, Rapid Connect infers it from the entry mode. |
TipAmount |
number (double) | Optional | The amount dedicated to the tip (this is an optional charge for the client with a default value configurable by the merchant) |
Track2 |
string | Optional | Credit card track data. Not required if using the No Swipe method. |
TransactionType |
integer (int32) | Required | Transaction Type | Name | Value | Description | |---|---|---| | CREDIT | 1 | Credit transaction | | CREDIT_WITH_TOKEN | 2 | Credit with token transaction | | Pre_Authorization | 3 | Credit preauthorization request | | Pre_Authorization_Completion | 4 | Credit preauthorization completion | | SaleDebit | 5 | Debit Card Sale transaction | | EBT | 6 | EBT Transaction | | GIFTCARD | 7 | Blackstone Gift Card transaction | |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for reference purposes only; must be unique. |
VerificationOverrides |
VerificationOverrides | Optional | Optional per-transaction overrides for the merchant's CVV, zip code, address and country verifications. Honored only for Rapid Connect; ignored for other processors. |
ZipCode |
string | Optional | Cardholder�s zip code. Not required if credit card is swiped. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/Sale' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Amount": 10.0,
"UserTransactionNumber": "unique-transaction-id",
"TransactionType": 1,
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Sale Response | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Debit Card Sale¶
/api/Transactions/SaleDebit
Process a debit card sale.
Request body¶
Schema: SaleDebitRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Amount |
number (double) | Required | Transaction amount as a JSON number. Quoted numeric strings are not part of the public contract. |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
CVN |
string | Optional | Credit card verification number (security code). Not required if credit card is swiped. |
CardDifferenceAmount |
number (double) | Optional | The amount dedicated to the card difference (this is an optional charge passed on to the user) |
CardNumber |
string | Optional | Credit card number. Not required if credit card isswiped. |
CashBackAmount |
number (double) | Optional | Cash back amount. |
CurrencyCode |
string | Optional | The Code of the currency to process the transaction. By default, USD dollar is used. |
CustomerAddress |
string | Optional | Optional address for the customer |
CustomerCity |
string | Optional | Optional city for the customer |
CustomerCountry |
string | Optional | Optional country for the customer |
CustomerEmail |
string | Optional | The email for the customer in the e-commerce transaction (optional) |
CustomerId |
integer (int32) | Optional | The merchant customer ID as a JSON integer. Quoted strings are not part of the public contract. |
CustomerPhone |
string | Optional | The phone number for the customer in the e-commerce transaction (optional) |
CustomerState |
string | Optional | Optional state for the customer |
DigWltProgType |
string | Optional | — |
DigWltToken |
string | Optional | — |
EmvData |
string | Optional | Contactless data. |
EnableCreditOnlinePin |
boolean | Optional | Enables online PIN only for ordinary Credit EMV sales on Rapid Connect with configured DUKPT. Defaults to false; Credit sales ignore residual PinBlock and KSN unless enabled. |
ExpDate |
string | Optional | Credit card expiration date. SaleWithToken accepts MMYY or MM/YY; other sale flows require MMYY. Not required if credit card is swiped. Rapid Connect token sales use the valid stored token expiration when available and otherwise require this field. |
ForceDuplication |
boolean | Optional | Indicates whether the payment should be executed even if a recent payment exists with the same signature. |
InvoiceNumber |
string | Optional | Optional invoice number associated with the transaction. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
KSN |
string | Optional | Optional DUKPT key serial number for the encrypted online PIN block. |
NameOnCard |
string | Optional | Cardholder Name. Not required if credit card is swiped. |
OrderReference |
string | Optional | Optional reference for the order in case it applies |
Password |
string | Required | Password of the client on the host. |
PaymentLinkId |
string | Optional | Optional Payment Link identifier when the transaction is paid from a payment link. |
PinBlock |
string | Optional | Optional encrypted online PIN block for Credit EMV. Supply together with KSN. |
PosCode |
string — ECommerce, Moto, RecurringBilling, Retail |
Optional | The condition in which the payment was captured |
PosEntryMode |
string — KeyEntered, AmexContactless, CredentialOnFile, Contactless, Swiped, AmexDigitalWallet, Chip, ChipFallbackSwipe, ChipFallbackManual |
Optional | The entry mode in which the payment was captured |
PurchaseCardLevel2 |
PurchaseCardLevel2Data | Optional | Optional Purchase Card Level 2 data sent to Rapid Connect for commercial card processing. |
SURI |
string | Optional | SURI number |
SaveCustomer |
boolean | Optional | This optional parameter indicates if the merchant wants to save the customer |
SaveToken |
boolean | Optional | Indicates to return a token for the card in case the transaction was successful |
SecureData |
string | Optional | The 3D secure data present once the 3D secure flow has been triggered for the transaction |
SecureTransactionId |
string | Optional | ID of the secure transaction |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
Street |
string | Optional | Cardholder�s billing street. Not required if credit card is swiped. |
SurchargeAmount |
number (double) | Optional | Optional surcharge amount as a JSON number. Direct API callers calculate and supply this value; the API does not derive it from the merchant's configured surcharge percentage. |
TaxAmount |
number (double) | Optional | The amount dedicated to the tax (this is an optional charge configurable by the merchant) |
TerminalEntryCapability |
string — Unspecified, NotUsed, MagneticStripeOnly, MagneticStripeAndKeyEntry, MagneticStripeKeyEntryAndChip, Barcode, ContactlessChip, Ocr, ChipOnly, ChipAndMagneticStripe, ManualEntryOnly, ContactlessMagneticStripe, Hybrid, DoesNotReadCardData |
Optional | Optional card entry capability of the terminal (Rapid Connect TermEntryCapablt): what the device can read, not how this card was read. Send Hybrid (12) from a terminal with magnetic stripe, chip and contactless readers. When EmvData is present it must be MagneticStripeKeyEntryAndChip, ContactlessChip, ChipOnly, ChipAndMagneticStripe or Hybrid. When omitted, Rapid Connect infers it from the entry mode. |
TipAmount |
number (double) | Optional | The amount dedicated to the tip (this is an optional charge for the client with a default value configurable by the merchant) |
Track2 |
string | Optional | Credit card track data. Not required if using the No Swipe method. |
TransactionType |
integer (int32) | Required | Transaction Type | Name | Value | Description | |---|---|---| | CREDIT | 1 | Credit transaction | | CREDIT_WITH_TOKEN | 2 | Credit with token transaction | | Pre_Authorization | 3 | Credit preauthorization request | | Pre_Authorization_Completion | 4 | Credit preauthorization completion | | SaleDebit | 5 | Debit Card Sale transaction | | EBT | 6 | EBT Transaction | | GIFTCARD | 7 | Blackstone Gift Card transaction | |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for reference purposes only; must be unique. |
VerificationOverrides |
VerificationOverrides | Optional | Optional per-transaction overrides for the merchant's CVV, zip code, address and country verifications. Honored only for Rapid Connect; ignored for other processors. |
ZipCode |
string | Optional | Cardholder�s zip code. Not required if credit card is swiped. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/SaleDebit' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Amount": 10.0,
"UserTransactionNumber": "unique-transaction-id",
"TransactionType": 1,
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Sale Debit Response | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Sale with Apple Pay¶
/api/Transactions/SaleWithApplePay
Process an Apple Pay sale transaction.
Request body¶
Schema: ApplePayRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Amount |
number (double) | Required | Transaction amount |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
CardDifferenceAmount |
number (double) | Optional | The amount dedicated to the card difference (this is an optional charge passed on to the user) |
CurrencyCode |
string | Optional | The Code of the currency to process the transaction. By default, USD dollar is used. |
CustomerEmail |
string | Optional | The email for the customer in the e-commerce transaction (optional) |
CustomerId |
integer (int32) | Optional | The ID of the merchant's customer |
InvoiceNumber |
string | Optional | Optional invoice number associated with the transaction. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
OrderReference |
string | Optional | Optional reference for the order in case it applies |
Password |
string | Required | Password of the client on the host. |
PaymentLinkId |
string | Optional | Optional Payment Link identifier when the transaction is paid from a payment link. |
SURI |
string | Optional | SURI number |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
SurchargeAmount |
number (double) | Optional | The amount dedicated to the surcharge (this is an optional charge passed on to the user) |
TaxAmount |
number (double) | Optional | The amount dedicated to the tax (this is an optional charge configurable by the merchant) |
TipAmount |
number (double) | Optional | The amount dedicated to the tip (this is an optional charge for the client with a default value configurable by the merchant) |
Token |
string | Required | Base64 encoded Apple Pay token used for payment authorization. The decoded JSON payload supports: { paymentData: { ... } }, { token: { ... } }, direct paymentData object { data, signature, version, header }, and also paymentData/token values as JSON strings. |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | A reference unique to this merchant, shared across endpoints and test/live modes. A previously reserved reference is rejected with ResponseCode 5; the original response is not replayed. Once reserved, the reference remains used even if processing fails. Reconcile an uncertain outcome before creating a new payment attempt. |
VerificationOverrides |
VerificationOverrides | Optional | Optional per-transaction overrides for the merchant's CVV, zip code, address and country verifications. Honored only for Rapid Connect; ignored for other processors. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/SaleWithApplePay' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Amount": 10.0,
"Token": "<token>",
"UserTransactionNumber": "unique-transaction-id",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Sale Response | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Sale with Google Pay¶
/api/Transactions/SaleWithGooglePay
Process a google pay sale transaction.
Request body¶
Schema: GooglePayRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Amount |
number (double) | Required | Transaction amount |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
CardDifferenceAmount |
number (double) | Optional | The amount dedicated to the card difference (this is an optional charge passed on to the user) |
CurrencyCode |
string | Optional | The Code of the currency to process the transaction. By default, USD dollar is used. |
CustomerEmail |
string | Optional | The email for the customer in the e-commerce transaction (optional) |
CustomerId |
integer (int32) | Optional | The ID of the merchant's customer |
InvoiceNumber |
string | Optional | Optional invoice number associated with the transaction. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
OrderReference |
string | Optional | Optional reference for the order in case it applies |
Password |
string | Required | Password of the client on the host. |
PaymentLinkId |
string | Optional | Optional Payment Link identifier when the transaction is paid from a payment link. |
PosCode |
string — ECommerce, Moto, RecurringBilling, Retail |
Optional | The condition in which the payment was captured |
PosEntryMode |
string — KeyEntered, AmexContactless, CredentialOnFile, Contactless, Swiped, AmexDigitalWallet, Chip, ChipFallbackSwipe, ChipFallbackManual |
Optional | The entry mode in which the payment was captured |
SURI |
string | Optional | SURI number |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
SurchargeAmount |
number (double) | Optional | The amount dedicated to the surcharge (this is an optional charge passed on to the user) |
TaxAmount |
number (double) | Optional | The amount dedicated to the tax (this is an optional charge configurable by the merchant) |
TipAmount |
number (double) | Optional | The amount dedicated to the tip (this is an optional charge for the client with a default value configurable by the merchant) |
Token |
string | Required | Base64 of the UTF-8 JSON token string from paymentMethodData.tokenizationData.token, not a plain credit card number. Token is required and cannot be empty or whitespace. |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | A reference unique to this merchant, shared across endpoints and test/live modes. A previously reserved reference is rejected with ResponseCode 5; the original response is not replayed. Once reserved, the reference remains used even if processing fails. Reconcile an uncertain outcome before creating a new payment attempt. |
VerificationOverrides |
VerificationOverrides | Optional | Optional per-transaction overrides for the merchant's CVV, zip code, address and country verifications. Honored only for Rapid Connect; ignored for other processors. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/SaleWithGooglePay' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Amount": 10.0,
"Token": "<token>",
"UserTransactionNumber": "unique-transaction-id",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Sale Response | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Sale with Token¶
/api/Transactions/SaleWithToken
Process a credit card sale transaction using a previously generated token.
TransactionType must be the JSON integer 2 (CREDIT_WITH_TOKEN). Amount and the optional
caller-calculated SurchargeAmount are JSON numbers. A quoted amount is not part of the public contract.
Token sales do not require 3D Secure authentication, SecureData or SecureTransactionId, even when
merchant settings enforce 3D Secure for card-entry sales. The same applies to subsequent recurring token sales.
After authentication and replay lookup, invalid Amount, TransactionType and missing Token are reported together
in Msg before reserving a new UserTransactionNumber. Error priority is Amount (506), type (501), then missing token (3).
Merchant-specific tax/card-difference rules and token lookup remain separate checks after these basic fields.
Zero amount is invalid, not a dry-run mode. A valid request can charge the card; this endpoint is not a validation-only API.
Example endpoint-specific fields:
{
"Amount": 10.00,
"TransactionType": 2,
"Token": "token-from-GetTokenForCard",
"SurchargeAmount": 0.30,
"UserTransactionNumber": "order-1001"
}
Request body¶
Schema: SaleWithTokenRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Amount |
number (double) | Required | Transaction amount as a JSON number. Quoted numeric strings are not part of the public contract. |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
CVN |
string | Optional | Credit card verification number (security code). Not required if credit card is swiped. |
CardDifferenceAmount |
number (double) | Optional | The amount dedicated to the card difference (this is an optional charge passed on to the user) |
CardNumber |
string | Optional | Credit card number. Not required if credit card isswiped. |
Comments |
string | Optional | Transaction comments |
CurrencyCode |
string | Optional | The Code of the currency to process the transaction. By default, USD dollar is used. |
CustomerAddress |
string | Optional | Optional address for the customer |
CustomerCity |
string | Optional | Optional city for the customer |
CustomerCountry |
string | Optional | Optional country for the customer |
CustomerEmail |
string | Optional | The email for the customer in the e-commerce transaction (optional) |
CustomerId |
integer (int32) | Optional | The merchant customer ID as a JSON integer. Quoted strings are not part of the public contract. |
CustomerPhone |
string | Optional | The phone number for the customer in the e-commerce transaction (optional) |
CustomerState |
string | Optional | Optional state for the customer |
DigWltProgType |
string | Optional | — |
DigWltToken |
string | Optional | — |
EmvData |
string | Optional | Contactless data. |
EnableCreditOnlinePin |
boolean | Optional | Enables online PIN only for ordinary Credit EMV sales on Rapid Connect with configured DUKPT. Defaults to false; Credit sales ignore residual PinBlock and KSN unless enabled. |
ExpDate |
string | Optional | Credit card expiration date. SaleWithToken accepts MMYY or MM/YY; other sale flows require MMYY. Not required if credit card is swiped. Rapid Connect token sales use the valid stored token expiration when available and otherwise require this field. |
ForceDuplication |
boolean | Optional | Indicates whether the payment should be executed even if a recent payment exists with the same signature. |
InvoiceNumber |
string | Optional | Optional invoice number associated with the transaction. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
KSN |
string | Optional | Optional DUKPT key serial number for the encrypted online PIN block. |
NameOnCard |
string | Optional | Cardholder Name. Not required if credit card is swiped. |
OrderReference |
string | Optional | Optional reference for the order in case it applies |
Password |
string | Required | Password of the client on the host. |
PaymentLinkId |
string | Optional | Optional Payment Link identifier when the transaction is paid from a payment link. |
PinBlock |
string | Optional | Optional encrypted online PIN block for Credit EMV. Supply together with KSN. |
PosCode |
string — ECommerce, Moto, RecurringBilling, Retail |
Optional | The condition in which the payment was captured |
PosEntryMode |
string — KeyEntered, AmexContactless, CredentialOnFile, Contactless, Swiped, AmexDigitalWallet, Chip, ChipFallbackSwipe, ChipFallbackManual |
Optional | The entry mode in which the payment was captured |
PurchaseCardLevel2 |
PurchaseCardLevel2Data | Optional | Optional Purchase Card Level 2 data sent to Rapid Connect for commercial card processing. |
SURI |
string | Optional | SURI number |
SaveCustomer |
boolean | Optional | This optional parameter indicates if the merchant wants to save the customer |
SaveToken |
boolean | Optional | Indicates to return a token for the card in case the transaction was successful |
SecureData |
string | Optional | The 3D secure data present once the 3D secure flow has been triggered for the transaction |
SecureTransactionId |
string | Optional | ID of the secure transaction |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
Street |
string | Optional | Cardholder�s billing street. Not required if credit card is swiped. |
SurchargeAmount |
number (double) | Optional | Optional surcharge amount as a JSON number. Direct API callers calculate and supply this value; the API does not derive it from the merchant's configured surcharge percentage. |
TaxAmount |
number (double) | Optional | The amount dedicated to the tax (this is an optional charge configurable by the merchant) |
TerminalEntryCapability |
string — Unspecified, NotUsed, MagneticStripeOnly, MagneticStripeAndKeyEntry, MagneticStripeKeyEntryAndChip, Barcode, ContactlessChip, Ocr, ChipOnly, ChipAndMagneticStripe, ManualEntryOnly, ContactlessMagneticStripe, Hybrid, DoesNotReadCardData |
Optional | Optional card entry capability of the terminal (Rapid Connect TermEntryCapablt): what the device can read, not how this card was read. Send Hybrid (12) from a terminal with magnetic stripe, chip and contactless readers. When EmvData is present it must be MagneticStripeKeyEntryAndChip, ContactlessChip, ChipOnly, ChipAndMagneticStripe or Hybrid. When omitted, Rapid Connect infers it from the entry mode. |
TipAmount |
number (double) | Optional | The amount dedicated to the tip (this is an optional charge for the client with a default value configurable by the merchant) |
Token |
string | Optional | The Token which identifies the credit card information. |
Track2 |
string | Optional | Credit card track data. Not required if using the No Swipe method. |
TransactionType |
integer (int32) | Required | Transaction Type | Name | Value | Description | |---|---|---| | CREDIT | 1 | Credit transaction | | CREDIT_WITH_TOKEN | 2 | Credit with token transaction | | Pre_Authorization | 3 | Credit preauthorization request | | Pre_Authorization_Completion | 4 | Credit preauthorization completion | | SaleDebit | 5 | Debit Card Sale transaction | | EBT | 6 | EBT Transaction | | GIFTCARD | 7 | Blackstone Gift Card transaction | |
UserName |
string | Required | User credential of the client on the host. |
UserTransactionNumber |
string | Required | The transaction identifier used for reference purposes only; must be unique. |
VerificationOverrides |
VerificationOverrides | Optional | Optional per-transaction overrides for the merchant's CVV, zip code, address and country verifications. Honored only for Rapid Connect; ignored for other processors. |
ZipCode |
string | Optional | Cardholder�s zip code. Not required if credit card is swiped. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/SaleWithToken' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Amount": 10.0,
"UserTransactionNumber": "unique-transaction-id",
"TransactionType": 1,
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Sale With Token Response | SaleResponse |
Example response
{
"Amount": 10.0,
"AppliedSurchargeAmount": 10.0,
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardDifferenceAmount": 10.0,
"CardType": "<card-type>",
"CustomerId": 1,
"EmvData": "<emv-data>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"SurchargeAmount": 10.0,
"TaxAmount": 10.0,
"TipAmount": 10.0
}
Validate Apple Pay Merchant Session¶
/api/Transactions/ValidateApplePayMerchant
Request body¶
Schema: ApplePayValidateMerchantRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
Initiative |
string | Required | — |
InitiativeContext |
string | Required | — |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
UserName |
string | Required | User credential of the client on the host. |
ValidationUrl |
string | Required | — |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/ValidateApplePayMerchant' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"ValidationUrl": "<validation-url>",
"Initiative": "<initiative>",
"InitiativeContext": "<initiative-context>",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | Merchant session object | object |
Verification Only¶
/api/Transactions/VerificationOnly
Request body¶
Schema: VerificationOnlyRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
Account |
string | Optional | Account Number in the Card. |
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
Cv |
string | Optional | CV verification message. |
ExpDate |
string | Optional | Expiration Date in the Card. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
Street |
string | Optional | Cardholder’s Street. |
UserName |
string | Required | User credential of the client on the host. |
Zip |
string | Optional | Cardholder’s zip code. Not required if credit card is swiped. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/VerificationOnly' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Verification Response | VerificationOnlyResponse |
Example response
{
"AuthorizationNumber": "<authorization-number>",
"Balance": "<balance>",
"CardType": "<card-type>",
"LastFour": "<last-four>",
"Msg": [
"<msg>"
],
"PaymentPlanInfo": {
"Description": "<description>",
"DisplayName": false,
"MonthlyFee": 1.0,
"NonSwipeDiscount": 1.0,
"NonSwipeTransactionFee": 1.0,
"PlanId": 1,
"PlanName": "<plan-name>",
"SwipeDiscount": 1.0,
"SwipeTransactionFee": 1.0
},
"ResponseCode": 200,
"ServiceReferenceNumber": "<service-reference-number>",
"avs": "<avs>",
"cv": "<cv>",
"displayMessage": "<display-message>",
"msoft_code": "<msoft-code>",
"phard_code": "<phard-code>",
"verbiage": "<verbiage>"
}
Verify Bank Identification Number¶
/api/Transactions/VerifyBin
Send the lookup value in Bin; BinNumber is not a supported alias. The response is flat at the top level: Scheme, Type, Brand, Country, Bank, ResponseCode, and Msg.
Request body¶
Schema: BinDataRequest
| Field | Type | Requirement | Description |
|---|---|---|---|
AppInfo |
string | Optional | Application information including language, version, platform, device model and OS. Format: "Lang: XX. Version: X.X.X. Platform: XXXX. DeviceModel: XXXX. OS: XXXX" Example: "Lang: Es. Version: 3.11.8. Platform: android. DeviceModel: dedede. OS: Android OS 13 / API-33" |
AppKey |
string | Required | Application Key which uniquely identifies your application as provided by the Blackstone system. |
AppType |
integer (int32) | Required | Application Type as provided by the Blackstone system. |
Bin |
string | Required | Bank Identification Number to look up. The JSON property name is Bin; BinNumber is not an alias. |
IpAddress |
string | Optional | The client's IP address. |
IsTest |
boolean | Optional | True if is a test sale |
Password |
string | Required | Password of the client on the host. |
Source |
string — ApiClient, BpaydPortal, BPaydApp, BatchCloser, RecurringBillingTask, BPaydPlugin, PaymentFrame, VirtualTerminal, PaymentLink, Recurring, Invoice, QuickPayment, TakePayment, QuickPaymentMobileApp, WordPress, Zoho, Xero, Odoo, GoHighLevel, TakePaymentMobileApp |
Optional | The source of the request |
UserName |
string | Required | User credential of the client on the host. |
cid |
integer (int32) | Required | Cashier ID – A number used to identify the merchant’s subclient. |
mid |
integer (int32) | Required | Merchant ID – A number used to identify the merchant. |
curl --request POST \
--url 'https://services.bmspay.com/api/Transactions/VerifyBin' \
--header 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"Bin": "<bin>",
"AppKey": "your-app-key",
"AppType": 1,
"mid": 1,
"cid": 1,
"UserName": "your-username",
"Password": "your-password",
"IsTest": true
}
JSON
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Verification Response | BinDataResponse |
Example response
{
"Bank": {
"Name": "<name>",
"Phone": "+1-555-0100",
"Url": "<url>"
},
"Brand": "<brand>",
"Country": {
"Alpha2": "<alpha2>",
"Emoji": "<emoji>",
"Name": "<name>"
},
"Msg": [
"<msg>"
],
"ResponseCode": 200,
"Scheme": "<scheme>",
"Type": "<type>",
"displayMessage": "<display-message>",
"verbiage": "<verbiage>"
}
Test endpoint to void a specific hardcoded refund (RefundId: 105452)¶
/api/Transactions/VoidRefundTest
Responses¶
| Status | Description | Schema |
|---|---|---|
| 200 | The Void Response | Response |