Bitcoin

Learn how to accept crypto payments.

Customers could pay for products using their Crypto wallets can do so through our gateway. The coins are transferred to uniquely generated bitcoin addresses. Upon network confirmation, the bitcoins are instantly converted to Fiat currency and settled to the merchant.

Please note that Bitcoin transactions are not reversible and it is not possible to stop someone from paying more or less to an address for a given transaction.

Merchants may choose to use our Bitcoin payment page or construct their own.

Jump to:

  • Request Parameters
  • Parameters for own payment page
  • Notification parameters for payment confirmation
  • Special cases
  • Possible customer experience

Payment request parameters:

It is possible to use Direct Integration or the Hosted Payment Integration to perform a bitcoin transaction. When using direct integration the response parameters should be handled by the merchant.
In addition to the standard request parameters for an authorization request the following additional request parameters are needed:

  • payment_method : The payment method ID - 18.
  • custom2 : This will be displayed in the customers’ cryptos wallet application when requesting the payment. Default value is the “orderid” parameter.
  • custom3 : This can be high, medium or low. Meaning of each field is described in annex “Bitcoin”. Default value is HIGH.
  • url_return : The URL to redirect from the crypto payment page if used.

Additional response parameters for direct integration:

How to handle the response parameters for direct integration:

  1. The payment authorization request response will contain the following additional parameters:
  • paymentAddress
  • bitcoin_address
  • btc_amount
  • expirationTime
  • status_check_url
  • redirect_url
  1. There are three possibilities for displaying the BitCoin address for payment to the end customer.
  • a) Redirect the end customer to our BitCoin address page found in redirect_url (see image Bitcoin payment page)
  • b) Use the “paymentAddress” to generate a clickable link (this should open a default Bitcoin software installed on the client’s device),
  • c) Generate QR code based on the “paymentAddress” that can be scanned using a smartphone with the Bitcoin wallet app installed.
  • d) Show the “bitcoin_address” for the customer to manually enter/copy-paste this in to client’s Bitcoin wallet.
  • e) If not using option 1 it is highly recommended to add a timer showing the expiration time of the transaction as any payment after that will be considered invalid. “expirationTime” gives the time in unixtimestamp.
  • f) The “status_check_url” can be used to query the system for the latest status of transaction. bitcoin_address received in the request has to be posted to this url in order to check the status of transaction. Response is same as for Notification URL. Possible values are: NEW, PAID, UNDERPAID, CONFIRMED, COMPLETED, EXPIRED, INVALID

Notification of final status of transaction:

Once a payment has been made or the transaction has expired. The server will post the change in status/final status of the transaction in the notification URL.
The following parameters are posted on the notification URL:

NameDescription
errorcode0 = success
2000 = pending
127002 = underpayment
Any other value = failed
transactionidGateway transaction ID.
securityA signature calculated the same way request
signature is calculated using the merchant secret.
typeorder if transaction is failed or pending and capture
if transaction successful
errormessageempty = successful
pending = tx still pending
“Transaction expired” or “Transaction invalid” = failed
orderidThis is the same value submitted in the payment
request.
remaining_amount*Only sent during an under/overpayment to show
amount still owed.
captured_amount**Actual amount captured.
remaining_amount_btc**Amount remaining in BitCoin.
  • Only sent as response to a status_check_url query.
    ** If partial captures are allowed these fields will be sent in the notification.

Notes on special and rare cases:

Transaction underpaid – this happens when the customer sends a lower amount during the payment. If this happens the customer can still top up to the full amount within 15 minutes. If this is not done the transaction will be failed. Status_check_url can be used to query the remaining_amount to be paid and thus customers can be informed in time to correct the problem.

Customer experience

Video :

https://api.powercash.de/wp/wp-content/uploads/BitcoinPayment.mp4

Payouts via Bitcoin

Bitcoin Payouts can be done in two ways:

  1. via the Credit Fund Transfer API.
  2. CSV batch files uploaded to our SFTP folder

Currently, only transfer amount request can be sent using Fiat Currency: USD or EUR.

It is the recommended way to transfer winnings/profit to your customer.

General Flow

When a CFT request is sent with a Bitcoin Address is sent to the server, the server converts the Fiat currency amount and places a transfer order in BTC. The server return “pending” status at this stage.

The payout transfer oder is then executed and once it is accepted by the Bitcoin Network, the status of the CFT is changed to Successful.

This status can be queried on the Transaction Diagnose interface.


1. Payout API

Below is the CFT URL for our test environment ( Credit fund transfer CFT )

**POST URL:** https://sandbox.powercash21.com/pay/backoffice/payment_cft

Request

The CFT API requires the following fields in the Request:

Field NameTypeLengthFormatMandatory?Description
merchantidalphanumeric40 charactersmerchant identification
orderidalphanumericmax. 30 charactersorderid in the merchant shop system
amountfloat
numeric
8.2
8
12345678.90
12345678
transaction amount
currencychar3ISO 4217 i.e. “EUR” or “USD”currency only EUR or USD
payment_methodnumericvalid payment method id18
signaturehex40 charactersSee Signature: checksum for validation of request
languagechar2ISO-639-1 alpha 2language in which the error messages will be displayed
cryptocurrencychar3i.e BTC, LTC etc.Cryptocurrency for the payout.
Field NameTypeLength/FormatMandatory?Description
coin_wallet_addressalphanumeric25- 35 charactersWallet Address where the payment will be sent to.

The interface requires the following customer information:

Field NameTypeLengthFormatMandatory?Description
firstnamealphanumericmax. 30 charactersfirst name
lastnamealphanumericmax. 30 characterslast name
streetalphanumericmax. 50 charactersstreet
zipalphanumericmax. 10 characterspostal code
cityalphanumericmax. 40 characterscity
statealphanumericmax. 30 charactersstate/province
countrychar3country (ISO 3166 alpha3)country
emailRFC 822max. 50 characterse-mail-address
custom1alphanumericmax. 255 characterscustom field for merchant
custom2alphanumericmax. 255 characterscustom field for merchant
custom3alphanumericmax. 255 characterscustom field for merchant

Response

The Response contains the following fields:

Field NameTypeContentDescription
statusnumericstatus0 = no error, 2000=pending. Any other value is an error code
errormessagealphanumericempty or error messageerror messages of the payment gateway, pending (for successfully accepted) or other error message
errmsgalphanumericempty or error messageerror messages of the payment gateway, pending (for successfully accepted) or other error message
(deprecated)
transactionidnumerictransactionid, mandatorypayment gateway transaction identification for the Payout
transidnumerictransidpayment gateway transaction identification for the CFT (deprecated)
amountnumericempty or amount valueamount
priceprice (deprecated)
currencycharempty or currency valuecurrency
orderidalphanumericempty or orderid valueorderid in the merchant shop system

Example:

  • CFT-request with Testnet BTC address

Request:

URL: https://sandbox.powercash21.com/pay/backoffice/payment_cft

Post data:

amount=40&coin_wallet_address=1Kth5gv22AHFg3QvwHNwZCrKULJDYhSoqG&cryptocurrency=BTC&currency=USD&merchantid=gateway_test&payment_method=18&signature=88bfce43395f426b7d261ef74360d2acaf4c500d&[email protected]&orderid=Inatec-Test&lastname=Mann&street=An der Welle 4&zip=60322&city=Frankfurt&country=DEU&firstname=Muster&state=HE&custom1=&custom2=&custom3=

Response:

transactionid=103330365&transid=103330365&status=2000&errormessage=pending&errmsg=pending&amount=10&price=10&currency=EUR&orderid=Inatec-Test

2. Payout via CSV batch file

Before it is possible to send payouts via CSV file we need to create a SFTP account. A prerequisite for such account is a SSH public key.

Please generate a SSH public-private key pair and send us the public key.

There are countless guides to generating ssh key pairs online but here is one you can refer to.

Please send the public key and your merchantid to [email protected] with subject: SFTP access request for Bitcoin payouts

Once you have access to our sftp server:

sftp.inatec.com

Please upload csv files of the following format:

payment_id,amount,currency,orderid,bitcoin_address
your_merchant_id,228.53,USD,your_system_orderid,39ELb36MMATuK4zxXGCQ61PNXXXXXXXX
your_merchant_id,500,USD,your_system_orderid,331XEp1cBg24uGmDG7RpXCTpXXXXXXXX

Please note:

  1. that amount needs to be in format XXX.XX or XXX. This means: 12.1 is invalid whereas 12.10 is valid
  2. files naming convention: YYYY-MM-DD-1.csv, YYYY-MM-DD-2 (for second batch file for the same date).
  3. From windows you can use Filezilla to upload files.
  4. Use commas to seperate the columns

Our Technical Support team is there to help you:
Email: [email protected]
Available Monday – Friday between 09:00 and 17:00 CET/CEST