1. Read before you start an integration

1.1. About Service

Bellow you can find scheme representing general flow.

flow 2
You can find detailed description of the flow here.

1.2. Testing of an integration

  • We will review implementation following those requirements

    • UTORG method representation The interface of our method on your web-page should strictly follow the rules, outlined in the document: Guidelines

    • Successful order execution using the orderInit method

    • Fail order using the orderInit method

    • Handle postback response with Order status and process it. (we’ll check it on your sandbox)

    • Provide success/fail URL where customer should be redirected.

  • Test data

    • Access to merchant account https://app-stage.utorg.pro. For integration/testing purposes please request a demo account from support team.

To test on behalf of an end customer in the "email" parameter of the order/init request, you should send any of your own emails - it will receive information about the payment status and access to profile which can access end customer (if he wants)
  • Test cards:

Please use any valid card (Visa/MC). We recommend https://www.bincodes.com/random-creditcard-generator/ On sandbox we permit more countries than on production so before release on production please request an actual list of supported countries.

  • If you’re whitelisting external partners you can find our IP’s here

    • Test crypto addresses Testnet crypto addresses should be used on our sandbox

1.3. Environments

2. Authorization

  • Basic

    • Basic authorisation requires to pass two variables in requests:

      • X-AUTH-SID will be provided by Utorg.pro support

      • X-AUTH-NONCE should be random string for each request

  • Advanced This authorisation type can be enabled by Utorg.pro support team, please request it if you’ll decide to use this type of an authorization.

    • Start with generating a key pair and provide to Utorg team your public key

    • X-AUTH-SIGN param should be passed. Please follow info bellow to test it.

Generate public/private key
openssl genrsa -out merchant.key 2048
openssl rsa -in merchant.key -pubout -out merchant.pub
An example how to validate the signing of the request
#!/usr/bin/env node

const crypto = require("crypto");
const fs = require('fs');
const path = require('path');
let pkey = fs.readFileSync(path.join(__dirname, 'merchant.key'));
let privateKey = crypto.createPrivateKey(pkey)
const request = {
  "type" : "FIAT_TO_CRYPTO",
  "currency" : "EUR",
  "amount" : 100.00,
  "externalId" : "uniq-id-001"
}
const requestData = JSON.stringify(request, null, 2);
const nonce = Date.now();
const data = nonce.toString() + " " + requestData;
const signature = crypto.createSign('RSA-SHA256')
                        .update(Buffer.from(data))
                        .sign(privateKey, 'base64');
console.log("X-AUTH-SID:", "YOUR SID");
console.log("X-AUTH-NONCE:", nonce);
console.log("X-AUTH-SIGN:", signature);
console.log("Request:", requestData)
console.log("Sign data:", data)

3. REST API

3.1. Merchant API

3.1.1. Partners orders controller

Init order

Initiate new order for purchase. In case of successful response, you will get URL where to redirect your customer to proceed with transaction.

Wallet address must be unique for each customer or transaction
Curl example
$ curl 'https://app.utorg.pro/api/merchant/v1/order/init' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'X-AUTH-SID: xMCvx83...7Gh09' \
    -H 'X-AUTH-NONCE: 123456' \
    -d '{
  "type" : "FIAT_TO_CRYPTO",
  "currency" : "BTC",
  "paymentCurrency" : "EUR",
  "paymentAmount" : 100.0,
  "externalId" : "some-external-id",
  "address" : "mmWjhvLvEzF8jpQC7jfygVH2zx7YkYyzqS",
  "email" : "[email protected]",
  "postbackUrl" : "https://merchant.com/utorg/callback",
  "successUrl" : "https://merchant.com/utorg/success",
  "failUrl" : "https://merchant.com/utorg/fail"
}'
HTTP Request
POST /api/merchant/v1/order/init HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-AUTH-SID: xMCvx83...7Gh09
X-AUTH-NONCE: 123456
Content-Length: 389
Host: app.utorg.pro

{
  "type" : "FIAT_TO_CRYPTO",
  "currency" : "BTC",
  "paymentCurrency" : "EUR",
  "paymentAmount" : 100.0,
  "externalId" : "some-external-id",
  "address" : "mmWjhvLvEzF8jpQC7jfygVH2zx7YkYyzqS",
  "email" : "[email protected]",
  "postbackUrl" : "https://merchant.com/utorg/callback",
  "successUrl" : "https://merchant.com/utorg/success",
  "failUrl" : "https://merchant.com/utorg/fail"
}
Request headers
Name Description

X-AUTH-SID

Authorization SID value

X-AUTH-NONCE

Authorization nonce value

Request parameters
Path Type Optional Description

type

String

false

Order type: FIAT_TO_CRYPTO

currency

String

false

Order crypto currency

paymentAmount

Number

true

Payment amount nominated in payment currency

paymentCurrency

String

true

If you’ll pass this parameter customer won’t be able change payment currency on UI

externalId

String

false

Unique ID of transaction on merchant platform

address

String

true

Crypto Wallet address (valid Crypto address).

email

String

true

Customer email address. If field will be provided, customer will see it on UI

postbackUrl

String

true

You can provide us global URL where we should send data via postback

successUrl

String

true

URL where to redirect customer after successful payment. (you can provide us URL which will be used for each order)

failUrl

String

true

URL where to redirect customer after failed payment. (you can provide us URL which will be used for each order)

The list of order types can be viewed in the order types table.
Success HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 768

{
  "success" : true,
  "timestamp" : 1645680840532,
  "data" : {
    "id" : 1000,
    "createdAt" : 1645680840531,
    "updatedAt" : 1645680840531,
    "externalId" : "some-external-id",
    "currency" : "BTC",
    "address" : "mmWjhvLvEzF8jpQC7jfygVH2zx7YkYyzqS",
    "paymentCurrency" : "EUR",
    "paymentCurrencyLocked" : true,
    "paymentAmountLocked" : false,
    "acceptedById" : 1,
    "status" : "NEW",
    "postbackUrl" : "https://merchant.com/utorg/callback",
    "url" : "https://app.utorg.pro/order/1000/transaction?pid=1000",
    "successUrl" : "https://merchant.com/utorg/success",
    "failUrl" : "https://merchant.com/utorg/fail",
    "type" : "FIAT_TO_CRYPTO",
    "kycInvolved" : false,
    "mId" : "356a192b7913b04c54574d18c28d46e6395428ab"
  }
}
Search order

Find order by it’s ID.

Curl example
$ curl 'https://app.utorg.pro/api/merchant/v1/order/find' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'X-AUTH-SID: xMCvx83...7Gh09' \
    -H 'X-AUTH-NONCE: 123456' \
    -d '{
  "id" : 1000
}'
HTTP Request
POST /api/merchant/v1/order/find HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-AUTH-SID: xMCvx83...7Gh09
X-AUTH-NONCE: 123456
Content-Length: 17
Host: app.utorg.pro

{
  "id" : 1000
}
Request headers
Name Description

X-AUTH-SID

Authorization SID value

X-AUTH-NONCE

Authorization nonce value

Success HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 665

{
  "success" : true,
  "cursor" : 1000,
  "left" : 0,
  "timestamp" : 1645680839725,
  "data" : [ {
    "id" : 1000,
    "createdAt" : 1645680839723,
    "updatedAt" : 1645680839723,
    "externalId" : "some-external-id1",
    "amount" : 1,
    "currency" : "BTC",
    "address" : "mzBc4XEFSdzCDcTxAgf6EZXgsZWpztRhef",
    "paymentCurrency" : "EUR",
    "paymentCurrencyLocked" : true,
    "paymentAmountLocked" : false,
    "paymentAmount" : 7900.0,
    "status" : "EXECUTED",
    "blockchainTxId" : "4c8af628c15d4e8bf0505f29ee2dde0fec9682e947d750b8da60e4e66b69e79e",
    "conversionRate" : 7877.6,
    "type" : "FIAT_TO_CRYPTO",
    "kycInvolved" : false
  } ]
}
Response fields
Path Type Description

success

Boolean

Request status

error

Object

Error information

cursor

Number

Page cursor

left

Number

Missed elements count

timestamp

Number

Response timestamp

data

Array

Response data

data[].id

Number

Unique Order identifier

data[].createdAt

Number

Order creation time

data[].updatedAt

Number

Order update time

data[].amount

Number

Order amount in crypto

data[].currency

String

Order crypto currency

data[].address

String

Wallet address

data[].paymentCurrency

String

Payment currency

data[].paymentAmount

Number

Payment amount

data[].externalId

String

Order external (merchant) identifier

data[].status

String

Order status

data[].blockchainTxId

String

Order blockchain transaction identifier

data[].postbackUrl

String

Postback URL (if exists)

data[].postbackSentAt

Number

Postback sent time

data[].postbackStatus

String

Postback sent status: EXECUTED or FAILED

data[].sendAmount

Number

Send amount value

data[].paymentCurrencyLocked

Boolean

End customer won’t be able to change payment currency during purchase process.

data[].paymentAmountLocked

Boolean

Order crypto amount will be recalculated instead of payment amount if rate changed since order init.

data[].requestedById

Number

Merchant identifier

data[].acceptedById

Number

Customer identifier

data[].conversionRate

Number

Conversion rate value

data[].error

String

Order error message

data[].type

String

Order type

data[].kycInvolved

Boolean

Is KYC invloved

The list of statuses can be viewed in the order statuses table.
List orders
Curl example
$ curl 'https://app.utorg.pro/api/merchant/v1/order/list' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'X-AUTH-SID: xMCvx83...7Gh09' \
    -H 'X-AUTH-NONCE: 123456' \
    -d '{
  "cursor" : 0,
  "limit" : 5,
  "filter" : {
    "dateFrom" : 46800000,
    "dateTo" : 1646285640703,
    "paymentCurrency" : [ "EUR" ],
    "status" : [ "EXECUTED" ]
  }
}'
HTTP Request
POST /api/merchant/v1/order/list HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-AUTH-SID: xMCvx83...7Gh09
X-AUTH-NONCE: 123456
Content-Length: 175
Host: app.utorg.pro

{
  "cursor" : 0,
  "limit" : 5,
  "filter" : {
    "dateFrom" : 46800000,
    "dateTo" : 1646285640703,
    "paymentCurrency" : [ "EUR" ],
    "status" : [ "EXECUTED" ]
  }
}
Request headers
Name Description

X-AUTH-SID

Authorization SID value

X-AUTH-NONCE

Authorization nonce value

Success HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 727

{
  "success" : true,
  "cursor" : 123456,
  "hasNext" : false,
  "timestamp" : 1645680840804,
  "data" : [ {
    "id" : 123456,
    "createdAt" : 1645680840804,
    "updatedAt" : 1645680840804,
    "amount" : 1,
    "currency" : "BTC",
    "address" : "mzBc4XEFSdzCDcTxAgf6EZXgsZWpztRhef",
    "paymentCurrency" : "EUR",
    "paymentCurrencyLocked" : true,
    "paymentAmountLocked" : false,
    "paymentAmount" : 70000,
    "acceptedById" : 1,
    "status" : "ACCEPTED",
    "url" : "https://app.utorg.pro/order/123456/transaction?pid=1000",
    "conversionRate" : 1.11,
    "type" : "FIAT_TO_CRYPTO",
    "kycInvolved" : false,
    "finalPaymentAmount" : 70000,
    "mId" : "356a192b7913b04c54574d18c28d46e6395428ab"
  } ]
}

3.1.2. Merchant settings controller

Get currencies list

Currencies which are available for purchase.

Curl example
$ curl 'https://app.utorg.pro/api/merchant/v1/settings/currency' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'X-AUTH-SID: xMCvx83...7Gh09' \
    -H 'X-AUTH-NONCE: 123456'
HTTP Request
POST /api/merchant/v1/settings/currency HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-AUTH-SID: xMCvx83...7Gh09
X-AUTH-NONCE: 123456
Host: app.utorg.pro
Request headers
Name Description

X-AUTH-SID

Authorization SID value

X-AUTH-NONCE

Authorization nonce value

Success HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 69

{
  "success" : true,
  "timestamp" : 1645680825809,
  "data" : [ ]
}
The list of types can be viewed in the currency types table.
Set merchant postback URL
Curl example
$ curl 'https://app.utorg.pro/api/merchant/v1/settings/postback' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'X-AUTH-SID: xMCvx83...7Gh09' \
    -H 'X-AUTH-NONCE: 123456' \
    -d '{
  "url" : "https://merchant.com/utorg/callback"
}'
HTTP Request
POST /api/merchant/v1/settings/postback HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-AUTH-SID: xMCvx83...7Gh09
X-AUTH-NONCE: 123456
Content-Length: 51
Host: app.utorg.pro

{
  "url" : "https://merchant.com/utorg/callback"
}
Request headers
Name Description

X-AUTH-SID

Authorization SID value

X-AUTH-NONCE

Authorization nonce value

Request parameters
Path Type Optional Description

url

String

false

Postback URL

Success HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 716

{
  "success" : true,
  "timestamp" : 1645680826023,
  "data" : {
    "postback" : {
      "url" : "https://merchant.com/utorg/callback",
      "publicKey" : "AAAAB3NzaC1yc2EAAAADAQABAAABgQC2tsj5BbjaGvIBAHXfMd6CtxhQEp8TY13ciUSSXahSsVvxchFeTPu1ol6iIle/E6Wd+ywpceyRpusOSuhn519tcYGaBy/ecdzUIOLe9OsNZd+1Q2q7zqriuQ93jAM+H4PsLW9GGN24hGUJvEAqf38bJrzg0st6XTJK6mulOn509omOQmud0H1GhfL3/ifjOsaG7sDQLa1BM+zt8x4kMIsZ61AW8PRX+g5PG+n3AYiSbhgD1A7eRaB+yMnS9AgabUNAwCq2Aj6mX3iJd/0EeEhO1YDouYJgmAUXTR8S4dgMiYC0nR+RiQESIMKl61YUGPORI51gYfxRsA+beBOK86qjRhllVOMuoc+kppr01sIQXN/Vd87XNs0hiH5agESyVn09/jmxsogWy19wHEbA8aIxNr9BIFw+sNdYHSFeZSDl5uEJ8eSX1pLSbLL6qey3T3VW/gsq5sVwMYjJwgW4kMIlcwDGiIeF59wx7O/9TdNL+THzlCQfu+zU6T1pEsoax3U="
    }
  }
}
Set order success URL
Curl example
$ curl 'https://app.utorg.pro/api/merchant/v1/settings/successUrl' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'X-AUTH-SID: xMCvx83...7Gh09' \
    -H 'X-AUTH-NONCE: 123456' \
    -d '{
  "url" : "https://merchant.com/utorg/success"
}'
HTTP Request
POST /api/merchant/v1/settings/successUrl HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-AUTH-SID: xMCvx83...7Gh09
X-AUTH-NONCE: 123456
Content-Length: 50
Host: app.utorg.pro

{
  "url" : "https://merchant.com/utorg/success"
}
Request headers
Name Description

X-AUTH-SID

Authorization SID value

X-AUTH-NONCE

Authorization nonce value

Request parameters
Path Type Optional Description

url

String

false

Success URL

Success HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 127

{
  "success" : true,
  "timestamp" : 1645680822916,
  "data" : {
    "successUrl" : "https://merchant.com/utorg/success"
  }
}
Set order fail URL
Curl example
$ curl 'https://app.utorg.pro/api/merchant/v1/settings/failUrl' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'X-AUTH-SID: xMCvx83...7Gh09' \
    -H 'X-AUTH-NONCE: 123456' \
    -d '{
  "url" : "https://merchant.com/utorg/fail"
}'
HTTP Request
POST /api/merchant/v1/settings/failUrl HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-AUTH-SID: xMCvx83...7Gh09
X-AUTH-NONCE: 123456
Content-Length: 47
Host: app.utorg.pro

{
  "url" : "https://merchant.com/utorg/fail"
}
Request headers
Name Description

X-AUTH-SID

Authorization SID value

X-AUTH-NONCE

Authorization nonce value

Request parameters
Path Type Optional Description

url

String

false

Fail URL

Success HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 121

{
  "success" : true,
  "timestamp" : 1645680826537,
  "data" : {
    "failUrl" : "https://merchant.com/utorg/fail"
  }
}

3.1.3. Merchant tools controller

Convert fiat assets to crypto

Convert amount from FIAT currency to CRYPTO currency for future order init.

Curl example
$ curl 'https://app.utorg.pro/api/merchant/v1/tools/convert' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'X-AUTH-SID: xMCvx83...7Gh09' \
    -H 'X-AUTH-NONCE: 123456' \
    -d '{
  "fromCurrency" : "EUR",
  "toCurrency" : "BTC",
  "paymentAmount" : 10000
}'
HTTP Request
POST /api/merchant/v1/tools/convert HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-AUTH-SID: xMCvx83...7Gh09
X-AUTH-NONCE: 123456
Content-Length: 79
Host: app.utorg.pro

{
  "fromCurrency" : "EUR",
  "toCurrency" : "BTC",
  "paymentAmount" : 10000
}
Request headers
Name Description

X-AUTH-SID

Authorization SID value

X-AUTH-NONCE

Authorization nonce value

Success HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 74

{
  "success" : true,
  "timestamp" : 1645680833917,
  "data" : 1.157943
}
Convert crypto assets to fiat

Convert amount from CRYPTO currency to FIAT currency for future order init.

Curl example
$ curl 'https://app.utorg.pro/api/merchant/v1/tools/convert' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'X-AUTH-SID: xMCvx83...7Gh09' \
    -H 'X-AUTH-NONCE: 123456' \
    -d '{
  "fromCurrency" : "EUR",
  "toCurrency" : "BTC",
  "amount" : 0.013
}'
HTTP Request
POST /api/merchant/v1/tools/convert HTTP/1.1
Content-Type: application/json;charset=UTF-8
X-AUTH-SID: xMCvx83...7Gh09
X-AUTH-NONCE: 123456
Content-Length: 72
Host: app.utorg.pro

{
  "fromCurrency" : "EUR",
  "toCurrency" : "BTC",
  "amount" : 0.013
}
Request headers
Name Description

X-AUTH-SID

Authorization SID value

X-AUTH-NONCE

Authorization nonce value

Success HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 53

{
  "success" : true,
  "timestamp" : 1645680833323
}

4. Direct flow

4.1. About this integration

This type of integration provides a possibility to integrate Utorg method without integration via Rest API. You will need to generate a link where to redirect your end Customer and all purchase processes will be handled by Utorg.

4.2. Flow diagram

flow 2
To implement possibility for end customer to go back to partner please provide your Success and Fail URLS to Utorg support team.

4.3. URL structure and description

The URL where to redirect customer contains mandatory and optional parameters

Basic URL with mandatory parameters:

<URL>/direct/<SID>/<Address>/<Currency>

Example

https://app-stage.utorg.pro/direct/testSID/mvmeaWyWiuVYdZdySgofAt6CmKhJbRhaWA/?&currency=BTC

Table 1. URL parameters description
Param Description

URL

Domain of Utorg, which must contain prefix "direct". You can find info about environments environments

SID

Unique partners identifier can be obtained via Utorg support.

Wallet address

A wallet address where assets will be sent after successful purchase.

currency

Crypto currency which customer will purchase

Additional (optional) parameters which can be passed via URL to pass customer a different experience

An example of URL which contains optional parameters

https://app-stage.utorg.pro/direct/testSID/mvmeaWyWiuVYdZdySgofAt6CmKhJbRhaWA/?&currency=BTC&amount=0.005&[email protected]&paymentCurrency=USD

Param Description

email

Customers email address which will be used for an authorisation

amount

Amount in crypto which customer will purchase

paymentCurrency

Fiat currency which will be used for a payment

paymentAmount

Amount in Fiat currency

Amount and paymentAmount can’t be used in same query, if both params will be passed via URL, Amount will be used to calculate payment amount.

4.4. Authorization via Wallet

4.4.1. Customers authorisation to Utorg via signature

This annex describes a flow which allows to Authorize customer on Utorg via signature provided by Partner. This feature is use-full for partners which don’t have a possibility to collect and store customer email. At this point customer skips OTP authorisation on second purchase.

General flow

  1. Partner generates a link where to redirect customer as it is described in section No. 4

  2. Partner adds additional query parameters to the URL which will allow to authorise Customer on Utorg.

  3. Customer makes a purchase

  4. Customer is redirected back to Partner via Success or Fail URL and asynchronously Utorg sends Crypto to an address which was provided via URL.

Steps for an integration

  1. Generate link as described in Section 4

  2. Add query parameters to query:

Param WEB3 ED25519

publicKey

ETH (or compatible) address

Base58 encoded public key

Example:

HvU3X4K1WgdG6hf738zU6PGjjV1H9sBAoChbpuM7xSZu

signature

A signed timestamp (in milliseconds) together addition with predefined text.

Example message to sign:

Access to UTORG. Timestamp: 1641812816000

A signed sha256 hash of concatenated public key and timestamp (in milliseconds).

Example message to sign:

sha256(HvU3X4K1WgdG6hf738zU6PGjjV1H9sBAoChbpuM7xSZu)

timestamp

Timestamp in ms which used to generate signature

Timestamp in ms which used to generate signature

alg

WEB3

ED25519

5. Annex

5.1. Detailed Purchase flow

flow 2
Table 2. Purchase flow steps description
Step No Description

1, 2

Customer starts process on Partners site.

Partner creates an API request orderInit

3

Utorg.pro creates an order and in response returns param URL which should be used in next step

4

Partner redirects customer to received URL or loads Utorg app via iFrame.

NOTE: To be able to use iFrame please follow requirements

5, 6

The Customer confirms his email and confirms his Country of Residence.

If customer passes step 5 successfully he is able to submit his card details.

7, 8, 9

UTORG accepts payment. In this step Utorg temporary BLOCKS asset on customer card. Charge operation is executed only when customer passes KYC procedure and/or other internal checks.

If KYC is rejected or there appears other reasons why transaction should be rejected Utorg UNBLOCKS assets on provided card.

NOTE: KYC is one time process, with second transactions Customer won’t be required to pass KYC procedure. More details about KYC policy can be found here

10.1, 10.2, 11

WHen customer finishes process (with success or fail) he can go back to partner site via links provided in order init or by configs on partner account.

Order gains status EXECUTED / ERROR

In parallel UTORG send a postback to partner by provided postbackUrl

An example of postback can be found here

12.1, 12.22, 13

Final processes where

* Partner provides service to customer

* Utorg sends Crypto to provided address in orderInit

5.2. Postback example

Here you can find an example of a postback which is sent from UTORG to the URL which you have to provide in orderInit request

{
"id": 31928166809894,
"createdAt": 1611310347398,
"updatedAt": 1611310604965,
"externalId": "25f19c42-3335-4b8f-9350-839ac68c6dfb",
"amount": 0.7,
"currency": "BTC",
"address": "2N72VXSb9hPLzVHkFM39aREB3ph3NGtJHuq",
"paymentCurrency": "EUR",
"paymentCurrencyLocked": true,
"paymentAmountLocked": false,
"paymentAmount": 19596.17,
"requestedById": 10179680225734,
"acceptedById": 31926285357326,
"acceptedByEmail": "[email protected]",
"status": "EXECUTED",
"type": "FIAT_TO_CRYPTO",
}
In case it is sent callback for order with status "SUCCESS" blockchain transaction hash is included in response

Validating the postback response

If you would like to validate our postback please request Public Key from our Support teeam. With provided Key you will be able to verify that you have received a postback from Utorg. Here is an example of a validation

const crypto = require("crypto");
// X-SIGN header value from postback response
const signature = ''
// Body of the payload as is
const body = ''
// Public key received from UTORG team
const publicKey = ''
// Convert to PEM for nodejs crypto: add prefix, posfix and split by 64 symbols. It doesn't need for java, golang etc.
const publicKeyPem = `-----BEGIN PUBLIC KEY-----
${publicKey.replace(/(.{64})/g,"$1\n")}
-----END PUBLIC KEY-----`
const verifier = crypto.createVerify('RSA-SHA256');
verifier.update(body);
const isValid = verifier.verify(publicKeyPem, signature, 'base64');
console.log("isValid? ", isValid);

5.3. Currencies types

Table 3. Currency types
Type Description

FIAT

A currency without intrinsic value that has been established as money, often by government regulation

CRYPTO

a digital asset designed to work as a medium of exchange that uses strong cryptography to secure financial transactions, control the creation of additional units, and verify the transfer of assets

5.4. Order types

Order types

Here you can find description of order types which are available for merchant on OrderInit method (Init order)

Type Description

FIAT_TO_CRYPTO

End customer pays fiat, crypto assets are sent to wallet address which was passed on orderInit.

5.5. Order statuses

Table 4. Order statuses
Status Description Final Receivable in callbacks?

NEW

New order. Expires in 24h if end customer haven’t continued payment.

N

N

ACCEPTED

Customer have begun to pay for transaction. Expires in 4h if end customer haven’t finished payment.

N

N

PROCESSING

Payment was started

N

N

VERIFICATION

Order processing is paused. Customer must pass KYC to finish the process.

N

N

EXECUTED

Payment processing was finished successfully. Partner can interpret this status as final, because crypto will be sent shortly.

N

Y

SUCCESS

Crypto transaction was created and received minimal amount of confirmations on blockchain.

Y

Y

EXPIRED

Order expired by timeout

Y

Y

ERROR

Order processing was finished with error or Customer failed to pass KYC.

Y

Y

SUSPICIOUS

Status which order can receive if Customers transaction haven’t passed Utorg pro AML checks.

N

N

5.6. Utorg IP addresses

Sandbox IP address

95.217.104.219

Production IP addresses

34.90.55.199, 34.91.26.119, 34.141.142.236