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:

Name

Description

errorcode

0 = success
2000 = pending
127002 = underpayment
Any other value = failed

transactionid

Gateway transaction ID.

security

A signature calculated the same way request
signature is calculated using the merchant secret.

type

order if transaction is failed or pending and capture
if transaction successful

errormessage

empty = successful
pending = tx still pending
“Transaction expired” or “Transaction invalid” = failed

orderid

This 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 Name

Type

Length

Format

Mandatory?

Description

merchantid

alphanumeric

40 characters

merchant identification

orderid

alphanumeric

max. 30 characters

orderid in the merchant shop system

amount

float
numeric

8.2
8

12345678.90
12345678

transaction amount

currency

char

3

ISO 4217 i.e. “EUR” or “USD”

currency only EUR or USD

payment_method

numeric

valid payment method id

18

signature

hex

40 characters

See Signature: checksum for validation of request

language

char

2

ISO-639-1 alpha 2

language in which the error messages will be displayed

cryptocurrency

char

3

i.e BTC, LTC etc.

Cryptocurrency for the payout.

Field Name

Type

Length/Format

Mandatory?

Description

coin_wallet_address

alphanumeric

25- 35 characters

Wallet Address where the payment will be sent to.

The interface requires the following customer information:

Field Name

Type

Length

Format

Mandatory?

Description

firstname

alphanumeric

max. 30 characters

first name

lastname

alphanumeric

max. 30 characters

last name

street

alphanumeric

max. 50 characters

street

zip

alphanumeric

max. 10 characters

postal code

city

alphanumeric

max. 40 characters

city

state

alphanumeric

max. 30 characters

state/province

country

char

3

country (ISO 3166 alpha3)

country

email

RFC 822

max. 50 characters

e-mail-address

custom1

alphanumeric

max. 255 characters

custom field for merchant

custom2

alphanumeric

max. 255 characters

custom field for merchant

custom3

alphanumeric

max. 255 characters

custom field for merchant

Response

The Response contains the following fields:

Field Name

Type

Content

Description

status

numeric

status

0 = no error, 2000=pending. Any other value is an error code

errormessage

alphanumeric

empty or error message

error messages of the payment gateway, pending (for successfully accepted) or other error message

errmsg

alphanumeric

empty or error message

error messages of the payment gateway, pending (for successfully accepted) or other error message
(deprecated)

transactionid

numeric

transactionid, mandatory

payment gateway transaction identification for the Payout

transid

numeric

transid

payment gateway transaction identification for the CFT (deprecated)

amount

numeric

empty or amount value

amount

price

price (deprecated)

currency

char

empty or currency value

currency

orderid

alphanumeric

empty or orderid value

orderid 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


Did this page help you?