Payment Page

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

Payment Page URL is returned as part of NewPaymentResponse as paymentPageUrl

Example:

{
  "paymentId" : "95bf1d853cf2e040f0ce219221f9b17206525941",
  "amount" : 0.03444190,
  "address" : "mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN",
  "label" : "Your store name",
  "message" : "Order of flowers and chocolates",
  "paymentAddress" : "bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN?amount=0.03444190&label=Your+store+name&message=Order+of+flowers+%26+chocolates",
  "expirationTime" : "2018-01-11T11:54:04Z",
  "exchangeRate" : 3299.6271,
  "merchantTransactionId" : "2015-03-10/123/1",
  "paymentPageUrl": "https://payments.bitcoinpaygate.com/95bf1d853cf2e040f0ce219221f9b17206525941"
}

As part of the payment response BPG 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.

{
  "amount" : 10.00,
  "currency" : "USD",
  "notificationUrl" : "https://example.com/pay",
  "anomalyNotificationUrl" : "https://example.com/anomaly",
  "message" : "Order of flowers and chocolates",
  "merchantTransactionId" : "2015-03-10/123/1",
  "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, we recommend re-using 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. BPG returns paymentPageUrl
  3. Customer is redirected by merchant to paymentPageUrl
  4. User pays correct amount of BTC to shown address
  5. Payment changes status to CONFIRMED
  6. After few seconds, customer is redirected to redirectUrls.confirmed

Considering handling UNCONFIRMED state

One exception is the UNCONFIRMED state. It is temporary and depends on various risk checks. Basically if this state is achieved it means that BPG needs to wait before confirming payment.

Payments in this state can wait between few minutes up to many hours (depending on Bitcoin 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.