Testing your integration¶

Use the Bpayd sandbox to verify your integration before processing live payments. The sandbox lets you exercise the same request and response flow as production without creating real transactions.

How testing works¶

Bpayd testing has two surfaces:

• API — send transactions with IsTest: true and inspect the response.
• Portal — review test transactions and reporting with Test Mode enabled.

The API and Portal use the same test data. This makes it possible to validate both sides of an integration: the request your application sends and the transaction your operations team sees.

Create a test transaction¶

Add IsTest: true to the request body for every transaction created in the sandbox.

Supported sandbox test cards¶

Use one of the supported card numbers listed below for an approved sandbox payment. No real funds move when the request is sent with IsTest: true. Never store or log a CVN/CVC/CVV.

Test successful payments by card brand¶

Use any future expiration date and the CVN length required by the card brand. These values simulate approved card payments in the Bpayd sandbox.

The following network-specific fixtures are available in the provider test suite. Use them only if the Bpayd merchant account and integration support the corresponding network or co-branded card:

The same numbers can be entered without spaces in API requests. For the regular Bpayd sale flow, send the number as CardNumber, the expiry as ExpDate, and the security code as CVN.

Test declined payments¶

Use these cards to verify that your integration does not fulfill an order when the issuer declines the payment. The response text and processor fields should be saved for troubleshooting; do not map Stripe-specific error names into the Bpayd API.

When testing CVN validation, always send a CVN. A missing CVN tests a different path and may bypass the validation rule depending on the merchant configuration.

{
  "mid": "YOUR_MERCHANT_ID",
  "UserName": "YOUR_USERNAME",
  "Password": "YOUR_PASSWORD",
  "AppType": 1,
  "AppKey": "YOUR_APP_KEY",
  "cid": 1,
  "IsTest": true,
  "Amount": 12.50,
  "UserTransactionNumber": "test-order-1001",
  "TransactionType": 1,
  "CardNumber": "4242424242424242",
  "ExpDate": "0830",
  "CVN": "123",
  "NameOnCard": "Test User",
  "ZipCode": "32606"
}

This is a simplified SaleRequest. Amount is a JSON number, TransactionType: 1 means a credit sale, and UserTransactionNumber must be unique for each request. The transaction fields vary by endpoint. Use the exact request shape shown in the API Reference and replace the placeholder credentials with the same merchant credentials you use in production.

Check the response¶

An accepted request returns the shared response fields used throughout the API:

{
  "ResponseCode": 200,
  "Msg": ["SUCCESS."],
  "verbiage": null
}

Do not mark an order as paid until the transaction-specific response confirms the payment. For a sale, save ServiceReferenceNumber, AuthorizationNumber, LastFour, and the final ResponseCode when they are present. ResponseCode: 200 means the operation completed successfully; it is not a substitute for storing the transaction reference and verifying the operation-specific result. Common request failures include invalid credentials (1), unauthorized operations (11), invalid parameters (506), and system errors (300).

Transaction types available in the sandbox¶

The sandbox supports the standard transaction lifecycle:

Verify a successful payment¶

Start with a successful Sale request. Confirm that your integration:

1. Sends IsTest: true.
2. Handles the approved response and stores the transaction identifier.
3. Shows the correct amount and status to the customer.
4. Can retrieve or reconcile the transaction using the returned identifier.
5. Displays the transaction in the Portal when Test Mode is enabled.

Repeat the same checks for PreAuth followed by Complete if your business flow separates authorization and capture.

Test errors and recovery¶

Your application should treat a declined or invalid response as an expected outcome, not as an unhandled exception. Test that your integration:

• shows a clear, actionable message to the customer;
• does not mark the order as paid;
• does not retry a request blindly;
• records the response for support and reconciliation; and
• allows the customer to correct the payment details or try again.

Use the response returned by the sandbox and the API Reference for the endpoint-specific status and error fields. Do not infer success from an HTTP status alone—inspect the transaction response.

Test 3D Secure flows¶

If your integration uses 3D Secure, test both paths:

• an authentication that completes successfully;
• a challenge or authentication that does not complete.

The expected result is that your application waits for the final payment result before confirming the order. Follow the 3D Secure Web or 3D Secure Mobile guide for the integration-specific flow.

3DS Integrator test cards¶

These cards belong to the 3DS Integrator sandbox, which is the provider used by Bpayd's 3DS integration. They are not general Bpayd card numbers and should not be used to test a regular sale without the 3DS flow. The provider documents that these cards work with any expiry date, amount, and cardholder name.

Use a CVN accepted by the payment form. These PANs are fixtures of the 3DS Integrator sandbox, not universal test cards and not general Bpayd card numbers. Do not use them to test a regular sale without the 3DS flow, and never use them in production.

Visa¶

Mastercard, Maestro, American Express, Discover, and Diners Club¶

Interpret the 3DS result¶

For a successful 3DS result, send both authenticationValue as SecureData and threeDsTransactionId as SecureTransactionId in the Bpayd payment request. Never continue payment solely because the browser challenge closed. See the 3DS Web guide for the complete callback and response handling rules.

3RI / merchant-initiated authentication cards¶

Use these only when testing the 3RI flow, not a normal browser challenge:

For a reproducible test, the provider documents amount 99.00, cardholder Test User, and test@example.com as example values. Use any expiry date that is in the future at the time of testing (for example, 12/30); do not copy a date that may expire, such as 12/26, after the end of 2026. These are provider examples, not Bpayd requirements; use the field formats required by your integration.

Test refunds and voids¶

Use a test transaction to verify the actions your support and operations teams need after payment:

• Void an authorization before it is captured.
• Refund a captured payment after the sale completes.

Confirm that the resulting status is shown consistently in your application, in the API response, and in the Portal. Keep the original transaction identifier associated with any follow-up action.

Full and partial refunds are available through the corresponding refund operations. Test that a partial refund cannot exceed the remaining amount and that the same amount cannot be refunded twice. A void is for an eligible authorization before settlement; after settlement, use a refund. If your integration uses a reversal operation, test it with the endpoint-specific eligibility rules in the API Reference.

Test Payment Links¶

Payment Links are a separate hosted-checkout flow. Test both fixed-amount and open-amount links:

1. Create a Payment Link in the sandbox.
2. Open the returned Bpayd URL.
3. Pay with one of the supported sandbox test cards.
4. Verify the customer return URL, if configured.
5. Retrieve the Payment Link and confirm that its status changes from Unpaid to Paid.
6. Confirm the payment in the Portal with Test Mode enabled.

Payment Links are one-time checkout URLs. Verify that an already-paid or disabled link cannot be used as a new payment. See the Payment Links guide for the create, retrieve, and disable operations.

Test webhooks and reconciliation¶

Webhooks notify your application about transaction activity after the API request. In the sandbox, test that your receiver:

• accepts the configured Bpayd payload version;
• verifies the webhook signature before processing the event;
• records the event and transaction identifier;
• safely ignores a duplicate delivery; and
• returns a successful response only after the event is safely stored.

Cover at least Sale, refund, void, pre-authorization, and completed pre-authorization events when those operations are part of your integration. Use the webhook setup guide, receiving events guide, and webhook reference for payloads, signatures, and delivery behavior.

When reconciling, compare the transaction identifier, amount, test flag, and final status. A webhook is useful for asynchronous updates, but it should not replace checking the immediate API response for the request that initiated the transaction.

Test payment methods beyond cards¶

If your integration supports alternative payment methods, run the same success, failure, and post-payment checks for each one:

• Apple Pay on the web, iOS, or Flutter
• Google Pay on the web, Android, or Flutter
• ATH Mobile

Use the sandbox environment and the test credentials or merchant configuration required by each method. Do not assume that a card test proves that a wallet or mobile flow works.

Review test data in the Portal¶

Portal pages show production data by default. Turn on Test Mode before reviewing sandbox transactions or dashboard statistics.

Transactions created through the API with IsTest: true appear in the Portal's test view. Transactions created directly in the Portal also follow the active mode: with Test Mode enabled they are test transactions; with it disabled they are live transactions.

Before going live¶

Use this checklist before switching to production:

• Remove test-only fixtures and test data from customer-facing screens.
• Confirm that live requests do not send IsTest: true.
• Verify credentials and endpoint configuration for production.
• Test the full order lifecycle, including refunds or voids where applicable.
• Verify that webhook handling and reconciliation are covered by your integration tests.
• Confirm that credentials, card data, and webhook secrets are not exposed in source code, browser logs, or application logs.
• Confirm that all production traffic uses HTTPS and that test fixtures are disabled.