× #message#
×

Warning

API Manual

Introduction

API

FIMA Change allows merchants to interact with payment gateway platform programmatically via HTTP API (view, add and cancel orders as well as check if a payment was successful). Service URL:

  • https://fimachange.com/api/v2/

Webhook / Instant Payment Notification (IPN)

Webhook Notifications URL can be set to notify the merchant when a payments status changes.


Performing a call

API calls are generated with a URL, followed by the endpoint URL and request data. Each API call requires:

  • pos_id

For localization you can use the locale parameter:

  • locale

To assign payment to a specific user, use the parameter:

  • user

Authentication

API calls are authenticated using HTTP Basic access authentication. You can generate your API key in your API Settings.


Return values

The API returns results in JSON format.


Error handling

On error there will be an err element in the result. Err value will contain the error description.


API reference

API calls are performed by sending a HTTP request to the URL starting with a link, followed by the endpoint URL and request data.

Method Request Response
GET /GetBuyRate/?pos_id={pos_id}&invoice_currency={invoice_currency}&invoice_amount={invoice_amount}&currency={currency} returns {invoice_currency, invoice_amount, currency, wait_time, network_processing_fee, rate, amount_exchange, amount, payment_id}
GET /StartBuyOrder/?pos_id={pos_id}&invoice_currency={invoice_currency}&reference_no={reference_no}&invoice_amount={invoice_amount}&currency={currency}&address={address}&payment_id={payment_id}&payer_ip_address={payer_ip_address}&payer_id={payer_id}&payer_user_agent={payer_user_agent} returns {invoice_currency, invoice_amount, currency, wait_time, network_processing_fee, rate, amount_exchange, amount, payment_id, address}
GET /ConfirmBuyOrder/?pos_id={pos_id}&address={address}&payment_id={payment_id} returns {address, currency}
GET /CheckPayment/?pos_id={pos_id}&currency={currency}&payment_id={payment_id}&address={address} returns {reference_no, inserted, invoice_amount, type, invoice_currency, amount, currency, confirmed, confirmed_time, status, wait_time, transfer_crypto_status, transfer_crypto_date_scheduled, transfer_crypto_transaction_id, state}

Replace {text} with request data: (e.g {pos_id} -> POS1, {invoice_currency} -> EUR)

Parameter Meaning
pos_id Point of service identification number for your reference (e.g. POS1, WEB1, ...)
payment_id Payment ID received from GetBuyRate
reference_no Optional reference number for your record (e.g. invoice or order number)
invoice_amount Amount on invoice for FIAT currency
invoice_currency Currency code for FIAT currency on invoice (EUR, USD..)
currency Cryptocurrency symbol (BTC, ETH..) to exchange the fiat into
address The consumers wallet address for the crypto purchased
payer_ip_address The IP address associated with the payer
payer_id Optional merchant-side payer identifier (max. 64 characters, allowed: 'A'-'Z', 'a'-'z', '0'-'9', '.', '_' and '-')
payer_user_agent Optional payer's User-Agent when API is used for website payments integration
transfer_crypto_auth_type Optional type for transfer crypto authentication. Valid types are "none" (default if not set) and "email_confirmation". None does not require any additional confirmation, "email_confirmation" requires confirmations via email.
Output Meaning
invoice_amount Amount on invoice for FIAT currency
invoice_currency Currency code for FIAT currency on invoice (EUR, USD..)
currency Cryptocurrency symbol (BTC, ETH..) to exchange the fiat into
wait_time Expected time to confirm
network_processing_fee Amount needed to transfer cryptocurrency from merchant to exchange
rate Exchange rate
amount_exchange Amount to exchange to get value on the invoice
amount Total amount to pay
payment_id Payment ID
address The consumers wallet address for the crypto purchased
reference_no Reference number
inserted Date and time of the transaction
type Type of order
confirmed Is transaction successful and confirmed
confirmed_time Time of confirmation
status Payment status description for user
state Payment states:
"waiting", "processing", "cancelled", "confirmed"

 waiting > cancelled
 waiting > processing > confirmed
 waiting > processing > cancelled
transfer_crypto_status Transfer crypto status: "approval needed", "pending", "sent"
transfer_crypto_date_scheduled Date when transfer crypto was scheduled
transfer_crypto_transaction_id Transfer crypto blockchain transaction id

GetBuyRate

The GetBuyRate API call is used to get buy rate information for the exchange of cryptocurrency to fiat currency.

Example:

https://fimachange.com/api/v2/GetBuyRate/?pos_id=web&invoice_currency=EUR&invoice_amount=5&currency=BTC

Response:

{
"invoice_currency":"EUR",
"invoice_amount":"50.00",
"currency":"BTC",
"wait_time":"120 minutes",
"network_processing_fee":"0.00016691",
"rate":"37900.3221",
"amount_exchange":"0.00131925",
"amount":"0.00115234",
"payment_id":"123e4567-e89b-12d3-a456-426614174000"
}

StartBuyOrder

The StartBuyOrder API call is used to initiate a buy order/purchase of cryptocurrency.

Example:

https://fimachange.com/api/v2/StartBuyOrder/?pos_id=web&invoice_currency=EUR&invoice_amount=5&currency=BTC&reference_no=12-23-789&address=33P6AnQfheFxnajXQwFas5jyo1nuhTY4M8&payment_id=123e4567-e89b-12d3-a456-426614174000

Response:

{
"invoice_currency":"EUR",
"invoice_amount":"50.00",
"currency":"BTC",
"wait_time":"120 minutes",
"network_processing_fee":"0.00016691",
"rate":"37900.3221",
"amount_exchange":"0.00131925",
"amount":"0.00115234",
"payment_id":"123e4567-e89b-12d3-a456-426614174000",
"address":"33P6AnQfheFxnajXQwFas5jyo1nuhTY4M8"
}

ConfirmBuyOrder

The ConfirmBuyOrder API call is used to confirm that you have received fiat from the consumer. This step is required to complete the transaction and schedule a transaction to send crypto to the consumer's wallet address.

Example:

https://fimachange.com/api/v2/ConfirmBuyOrder/?pos_id=web&payment_id=123e4567-e89b-12d3-a456-426614174000&address=33P6AnQfheFxnajXQwFas5jyo1nuhTY4M8

Response:

{
"address":"33P6AnQfheFxnajXQwFas5jyo1nuhTY4M8",
"currency":"BTC"
}

CheckPayment

The CheckPayment API call is used to check the status of a buy order.

Example:

https://fimachange.com/api/v2/CheckPayment/?pos_id=web&payment_id=123e4567-e89b-12d3-a456-426614174000&currency=BTC&address=33P6AnQfheFxnajXQwFas5jyo1nuhTY4M8

Response:

{
"reference_no":"12-23-789",
"inserted":"2021-08-06 08:23:24",
"invoice_currency":"EUR",
"invoice_amount":"50.00",
"type":"Buy",
"amount":"0.00115234",
"currency":"BTC",
"confirmed":true,
"confirmed_time":"2021-08-06 08:27:03",
"status":"Confirmed",
"wait_time":"120 minutes",
"transfer_crypto_status":"pending",
"transfer_crypto_date_scheduled":"2021-08-06 08:27:37",
"state":"confirmed"
}

×