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:
- The payment authorization request response will contain the following additional parameters:
- paymentAddress
- bitcoin_address
- btc_amount
- expirationTime
- status_check_url
- redirect_url
- 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.mp4Payouts via Bitcoin
Bitcoin Payouts can be done in two ways:
- via the Credit Fund Transfer API.
- 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 | |
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¤cy=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¤cy=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:
- that amount needs to be in format XXX.XX or XXX. This means: 12.1 is invalid whereas 12.10 is valid
- files naming convention: YYYY-MM-DD-1.csv, YYYY-MM-DD-2 (for second batch file for the same date).
- From windows you can use Filezilla to upload files.
- 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
Updated over 1 year ago