API Docs

Payment Page

Payment Page is the suggested way of how payment processing with Bitclear API works.

Payment Page URL is returned as part of NewPaymentResponse as paymentPageUrl

Full specification and example

As part of the payment response Bitclear API will return paymentPageUrl. This is the website that can be embedded, or a user can be redirected to in order to pay.

Payment Page can be both used as embedded in HTML page that is provided by PSP or Merchant, or it can be used independently - customer can be redirected to it.

Redirects

Payment Page utilizes redirect URLs that are provided as part of NewPaymentRequest. Currently, 4 different redirect URLs are supported.

{
  ...
  "redirectUrls" : {
    "expired": "http://shop.example.com/2015-03-10/123/1/expired",
    "confirmed": "http://shop.example.com/2015-03-10/123/1/confirmed",
    "invalid": "http://shop.example.com/2015-03-10/123/1/invalid",
    "unconfirmed": "http://shop.example.com/2015-03-10/123/1/unconfirmed"
  }
}

The redirectUrls attribute is optional, and Payment Page can be used without it, but when redirect URLs are provided, the customer will be redirected to the URL that matches the state of the payment.

In case any of the redirect URLs isn't provided and payment reaches that state, customer will not be redirected anywhere.

In case merchant doesn't support any of the states, it is recommended to re-use URL for any other state, so that customer will be redirected back to the store instead of staying on the Payment Page.

Example:

  1. New payment request (with all redirectUrls values set)
  2. Bitclear API returns paymentPageUrl
  3. Customer is redirected by merchant to paymentPageUrl
  4. User pays correct amount of BTC to the payment address
  5. Payment changes status to CONFIRMED
  6. After few seconds, customer is redirected to redirectUrls.confirmed

Considering handling UNCONFIRMED state

The UNCONFIRMED state is temporary and depends on various risk checks. Basically if this state is achieved it means that Bitclear API needs to wait before confirming payment.

Payments in this state can wait between few minutes up to many hours (depending on Cryptocurrency network conditions, this is out of our control).

Depending on your scenario, you can set redirectUrls.unconfirmed equal to redirectUrls.confirmed which means that once UNCONFIRMED is reached, customer will be redirected to the same page as if CONFIRMED was reached.

In other case, you can leave this parameter unset (simply omit redirectUrls.unconfirmed JSON attribute), in this case user will remain on Payment Page until payment reaches CONFIRMED.