Shell Python

Introduction

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Accept fiat payments. Personal and business wallet - all in one.

The YamalPay API provides a simple and powerful REST API to integrate fiat payments into your business or application. This API reference provides information on available endpoints and how to interact with them.

Authentication

Authorized request example

# You can also use wget
curl -X GET https://api.yamalpay.io/v1/payments/ \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.get('https://api.yamalpay.io/v1/payments/', headers = headers)

print(r.json())

Most requests to the YamalPay API must be authenticated with an API key. You can get your API key in your Account Info page.

Authenticated API requests should be made with a x-api-key header. Your secret API key should be passed as the value.

If authentication fails, a JSON object with an error message will be returned as a response along with HTTP status 401.

Versioning

The URLs for the various resources use the following pattern:

https://api.yamalpay.io/v{version}/{operation-specific component}

The components of the URL are:

version - the API version. Currently there is only one version, "1", in operation operation-specific component - this identifies the actual operation you want to do, eg /payments for getting a list of payments

Thus the URL getting a list of the orders for the authenticated user is https://api.yamalpay.io/v1/payments

Rate Limits

Our API enforces rate limits to ensure fair usage and prevent abuse. The rate limits are based on the number of requests per minute and vary depending on the endpoint. If you exceed the rate limit, you will receive a 429 Too Many Requests response.

Rate Limiting Strategies

To avoid hitting the rate limit, we recommend the following strategies:

If you require a higher rate limit or have any questions about our rate limiting policies, please contact us at support@yamalpay.io.

Pagination

All GET endpoints which return an object list support cursor based pagination with pagination information inside a pagination object. Use parameter page and limit to configure pagination. Default limit is set to 50 but values up to 100 are permitted.

Example responses

200 Response

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "resource": "payment",
      "code": "YJM5BAID",
      "name": "Product",
      "description": "The best Product",
      "amount": 10,
      "currency": "USD",
      "hosted_url": "https://pay.yamalpay.io/payments/YJM5BAID",
      "success_url": "https://example.com",
      "fail_url": "https://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "confirmed_at": "2019-08-24T14:15:22Z",
      "transactions": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "amount": 10,
          "currency": "USD",
          "status": "Approved",
          "account": "Shop",
          "payment_service": "H2H Ru",
          "payment_service_type": "bankcard",
          "created_at": "2019-08-24T14:15:22Z"
        }
      ],
      "timeline": [
        {
          "event": "Opened",
          "created_at": "2019-08-24T14:15:22Z"
        },
        {
          "event": "Pending",
          "created_at": "2019-08-24T14:15:22Z"
        },
        {
          "event": "Approved",
          "created_at": "2019-08-24T14:15:22Z"
        },
      ],
      "metadata": {
        "user_id": 123
      },
      "is_recurring": false,
      "recurrent": {
        "id": 1
      }
    }
  ],
  "total": 1,
  "page": 1,
  "size": 5,
  "pages": 1
}

Parameters

Name Description
total Total objects in query
page Page of query
size Number of results per call. Accepted values: 0 - 100. Default 50

Errors

All error messages include a type identifier and a human readable message. validation_error with status code 400 is returned when the validation of the resource fails on POST or PUT/PATCH requests. Response contains errors field with a list of errors.

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The object requested is hidden for administrators only.
404 Not Found -- The specified object could not be found.
405 Method Not Allowed -- You tried to access a object with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The object requested has been removed from our servers.
422 Validation Error -- Your request data or params are invalid.
429 Too Many Requests -- You're requesting too many objects! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503, 509 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Webhooks

Webhooks make it easier to integrate with YamalPay by allowing you to subscribe to a set of events. You can subscribe to the events by going to your settings page and adding a new webhook subscription. When you create a new subscription, you can specify what events you would like to receive updates for.

Example of a webhook payload

{
    "event": "payment.completed",
    "created_at": "2022-07-31T20:50:02Z",
    "data": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "resource": "payment",
        "code": "YJM5BAID",
        "name": "Product",
        "description": "The best Product",
        "amount": 10,
        "currency": "USD",
        "hosted_url": "https://pay.yamalpay.io/payments/YJM5BAID",
        "success_url": "https://example.com",
        "fail_url": "https://example.com",
        "created_at": "2019-08-24T14:15:22Z",
        "expires_at": "2019-08-24T14:15:22Z",
        "confirmed_at": "2019-08-24T14:15:22Z",
        "transactions": [
            {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "amount": 10,
            "currency": "USD",
            "status": "Approved",
            "account": "Shop",
            "payment_service": "H2H Ru",
            "payment_service_type": "bankcard",
            "created_at": "2019-08-24T14:15:22Z"
            }
        ],
        "timeline": [
            {
            "event": "Opened",
            "created_at": "2019-08-24T14:15:22Z"
            },
            {
            "event": "Pending",
            "created_at": "2019-08-24T14:15:22Z"
            },
            {
            "event": "Approved",
            "created_at": "2019-08-24T14:15:22Z"
            },
        ],
        "metadata": {
          "user_id": 123
        },
        "is_recurring": false,
        "recurrent": {
          "id": 1
        }
    }
}

Events

Event Description
payment.created New payment is created
payment.completed Transaction has been confirmed and the associated payment is completed
payment.expired Payment has been expired
payment.unresolved Payment had some problems
payment.resolved Payment has been resolved
payment.closed Payment has been closed
transaction.refunded Transaction has been refunded
withdrawal.completed Withdrawal has been completed

Fields

Field Type Description
event WebhookEvent Webhook event
created_at timestamp Delivery time
data object Corresponding resource object

Securing Webhooks

Because of the way webhooks work, attackers can impersonate services by simply sending a fake webhook to an endpoint. Think about it: it's just an HTTP POST from an unknown source. This is a potential security hole for many applications, or at the very least, a source of problems.

In order to prevent it, YamalPay signs every webhook and its metadata with a unique key for each endpoint. This signature can then be used to verify the webhook indeed comes from YamalPay, and only process it if it is.

Verifying Webhook with the Svix Libraries

First install the libraries if you haven't already:

# Install cURL. E.g. on arch linux:
pacman -S curl

pip install svix

The payload is the raw (string) body of the request, and the headers are the headers passed in the request.

Then verify webhooks using the code below. 

No easy way to verify the signature just with cURL.

from svix.webhooks import Webhook

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

# These were all sent from the server
headers = {
  "svix-id": "msg_p5jXN8AQM9LWM0D4loKWxJek",
  "svix-timestamp": "1614265330",
  "svix-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=",
}
payload = '{"test": 2432232314}'

wh = Webhook(secret)
# Throws on error, returns the verified content on success
payload = wh.verify(payload, headers)

Verifying Webhook manually

Each webhook call includes three headers with additional information that are used for verification:

Constructing the signed content The content to sign is composed by concatenating the id, timestamp and payload, separated by the full-stop character ..

In code, it will look something like:

signed_content = "${svix_id}.${svix_timestamp}.${body}"

Where body is the raw body of the request. The signature is sensitive to any changes, so even a small change in the body will cause the signature to be completely different. This means that you should not change the body in any way before verifying.

Determining the expected signature

YamalPay uses an HMAC with SHA-256 to sign its webhooks.

So to calculate the expected signature, you should HMAC the signed_content from above using the base64 portion of your signing secret (this is the part after the whsec_ prefix) as the key. For example, given the secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw you will want to use MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw.

This generated signature should match one of the ones sent in the Svix-Signature header.

The Svix-Signature header is composed of a list of space delimited signatures and their corresponding version identifiers. The signature list is most commonly of length one. Though there could be any number of signatures. For example:

v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=

Make sure to remove the version prefix and delimiter (e.g. v1,) before verifying the signature.

Please note that to compare the signatures it's recommended to use a constant-time string comparison method in order to prevent timing attacks.

Verify timestamp

As mentioned above, YamalPay also sends the timestamp of the attempt in the Svix-Timestamp header. You should compare this timestamp against your system timestamp and make sure it's within your tolerance in order to prevent timestamp attacks.

Payments

To request a fiat payment, you create a payment. You can create and view payments. Payments are identified by a unique code.

Statuses

Status Description
Opened Payment is opened and waiting for client to chose payment method
Pending Client has chosen payment method and waiting for transaction
Approved Transaction has been completed successfully
Expired Payment request expired after appointed time
Unresolved Transaction confirmed but the payment diverged from what was expected
Resolved Merchant marked the payment as resolved
Closed Request cancelled -- only new unpaid payments can be cancelled

Get Payments

Code samples

# You can also use wget
curl -X GET https://api.yamalpay.io/v1/payments/ \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.get('https://api.yamalpay.io/v1/payments/', headers = headers)

print(r.json())

GET /payments/

Returns all payments

Example responses

200 Response

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "resource": "payment",
      "code": "YJM5BAID",
      "name": "Product",
      "description": "The best Product",
      "amount": 10,
      "currency": "USD",
      "hosted_url": "https://pay.yamalpay.io/payments/YJM5BAID",
      "success_url": "https://example.com",
      "fail_url": "https://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "confirmed_at": "2019-08-24T14:15:22Z",
      "transactions": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "amount": 10,
          "currency": "USD",
          "status": "Approved",
          "account": "Shop",
          "payment_service": "H2H Ru",
          "payment_service_type": "bankcard",
          "created_at": "2019-08-24T14:15:22Z"
        }
      ],
      "timeline": [
        {
          "event": "Opened",
          "created_at": "2019-08-24T14:15:22Z"
        },
        {
          "event": "Pending",
          "created_at": "2019-08-24T14:15:22Z"
        },
        {
          "event": "Approved",
          "created_at": "2019-08-24T14:15:22Z"
        },
      ],
      "metadata": {
        "user_id": 123
      },
      "is_recurring": false,
      "recurrent": {
        "id": 1
      }
    }
  ],
  "total": 1,
  "page": 1,
  "size": 5,
  "pages": 1
}

Responses

Status Meaning Description Schema
200 OK Successful Response Page_PaymentResponseSchema_

Create Payment

Code samples

# You can also use wget
curl -X POST https://api.yamalpay.io/v1/payments/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' \
  -d '{
    "name": "Product",
    "description": "The best Product",
    "amount": 10,
    "currency": "USD",
    "is_recurring": false,
    "metadata": {
        "user_id": 123
    },
    "success_url": "https://google.com",
    "fail_url": "https://google.com",
    "ttl": 3600
  }'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}
data = {
  "name": "Product",
  "description": "The best Product",
  "amount": 10,
  "currency": "USD",
  "is_recurring": False,
  "metadata": {
    "user_id": 123
  },
  "success_url": "https://google.com",
  "fail_url": "https://google.com",
  "ttl": 3600
}

r = requests.post('https://api.yamalpay.io/v1/payments/', headers=headers, json=data)

print(r.json())

POST /payments/

Body parameter

{
  "name": "Product",
  "description": "The best Product",
  "amount": 10,
  "currency": "USD",
  "is_recurring": false,
  "metadata": {
    "user_id": 123
  },
  "success_url": "https://google.com",
  "fail_url": "https://google.com",
  "ttl": 3600
}

To get paid in fiat, you need to create a payment object and provide the user with an available payment services.

Parameters

Name Type Required Description
name string (255) true Payment name
description string (255) false More detailed description of the payment
amount integer true Payment amount
currency Currency true Payment currency
is_recurring boolean false Recurring payment
metadata object false Developer defined key value pairs
success_url string(uri) false Redirect URL after successful payment
fail_url string(uri) false Redirect URL after cancelled payment
ttl integer false Time to live in seconds

Example responses

201 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "resource": "payment",
  "code": "YJM5BAID",
  "name": "Product",
  "description": "The best Product",
  "amount": 10,
  "currency": "USD",
  "hosted_url": "https://pay.yamalpay.io/payments/YJM5BAID",
  "success_url": "https://example.com",
  "fail_url": "https://example.com",
  "created_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "confirmed_at": "2019-08-24T14:15:22Z",
  "transactions": [],
  "timeline": [
    {
      "event": "Opened",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "metadata": {
    "user_id": 123
  },
  "is_recurring": false,
  "recurrent": {
    "id": 1
  }
}

Responses

Status Meaning Description Schema
201 Created Successful Response PaymentResponseSchema
422 Unprocessable Entity Validation Error HTTPValidationError

Show Payment

Code samples

# You can also use wget
curl -X GET https://api.yamalpay.io/v1/payments/{id}/ \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.get('https://api.yamalpay.io/v1/payments/{id}/', headers = headers)

print(r.json())

GET /payments/{id}/

Retrieves the details of a payment that has been previously created. Supply the unique payment code that was returned when the payment was created. This information is also returned when a payment is first created.

Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "resource": "payment",
  "code": "YJM5BAID",
  "name": "Product",
  "description": "The best Product",
  "amount": 10,
  "currency": "USD",
  "hosted_url": "https://pay.yamalpay.io/payments/YJM5BAID",
  "success_url": "https://example.com",
  "fail_url": "https://example.com",
  "created_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "confirmed_at": "2019-08-24T14:15:22Z",
  "transactions": [],
  "timeline": [
    {
      "event": "Opened",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "metadata": {
    "user_id": 123
  },
  "is_recurring": false,
  "recurrent": {
    "id": 1
  }
}

Responses

Status Meaning Description Schema
200 OK Successful Response PaymentResponseSchema
404 Not Found Not Found Error None

Cancel Payment

Code samples

# You can also use wget
curl -X PATCH https://api.yamalpay.io/v1/payments/{id}/cancel \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.patch('https://api.yamalpay.io/v1/payments/{id}/cancel', headers = headers)

print(r.json())

PATCH /payments/{id}/cancel

Cancels a payment that has been previously created. Supply the unique payment code that was returned when the payment was created.

Note: Only new payments can be successfully canceled. Once transaction is detected, payment can no longer be canceled.

Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "resource": "payment",
  "code": "YJM5BAID",
  "name": "Product",
  "description": "The best Product",
  "amount": 10,
  "currency": "USD",
  "hosted_url": "https://pay.yamalpay.io/payments/YJM5BAID",
  "success_url": "https://example.com",
  "fail_url": "https://example.com",
  "created_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "confirmed_at": "2019-08-24T14:15:22Z",
  "transactions": [],
  "timeline": [
    {
      "event": "Opened",
      "created_at": "2019-08-24T14:15:22Z"
    },
    {
      "event": "Canceled",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "metadata": {
    "user_id": 123
  },
  "is_recurring": false,
  "recurrent": {
    "id": 1
  }
}

Responses

Status Meaning Description Schema
200 OK Successful Response PaymentResponseSchema
400 Bad Request Bad Request Error None
404 Not Found Not Found Error None

Resolve Payment

Code samples

# You can also use wget
curl -X PATCH https://api.yamalpay.io/v1/payments/{id}/resolve \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.patch('https://api.yamalpay.io/v1/payments/{id}/resolve', headers = headers)

print(r.json())

PATCH /payments/{id}/resolve

Resolve a payment that has been previously marked as unresolved. Supply the unique payment code that was returned when the payment was created.

Note: Only unresolved payments can be successfully resolved. For more on unresolved payments, visit the Payment section of this reference.

Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "resource": "payment",
  "code": "YJM5BAID",
  "name": "Product",
  "description": "The best Product",
  "amount": 10,
  "currency": "USD",
  "hosted_url": "https://pay.yamalpay.io/payments/YJM5BAID",
  "success_url": "https://example.com",
  "fail_url": "https://example.com",
  "created_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "confirmed_at": "2019-08-24T14:15:22Z",
  "transactions": [],
  "timeline": [
    {
      "event": "Opened",
      "created_at": "2019-08-24T14:15:22Z"
    },
    {
      "event": "Unresolved (Underpaid)",
      "created_at": "2019-08-24T14:15:22Z"
    },
    {
      "event": "Resolved",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "metadata": {
    "user_id": 123
  },
  "is_recurring": false,
  "recurrent": {
    "id": 1
  }
}

Responses

Status Meaning Description Schema
200 OK Successful Response PaymentResponseSchema
400 Bad Request Bad Request Error None
404 Not Found Not Found Error None

Recurrents

The YamalPay Recurrents API allows you to create and manage recurring payments.

Get available Recurrents

Code samples

# You can also use wget
curl -X GET https://api.yamalpay.io/v1/recurrents/ \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.get('https://api.yamalpay.io/v1/recurrents/', headers=headers)

print(r.json())

GET /recurrents/

Get all recurrents

Responses

Example responses

200 Response

{
  "items": [
    {
      "id": 1,
    }
  ],
  "total": 1,
  "page": 1,
  "size": 5,
  "pages": 1
}

Responses

Status Meaning Description Schema
200 OK Successful Response Page_PaymentServiceResponseSchema_
422 Unprocessable Entity Validation Error HTTPValidationError

Charge Recurrent

Code samples

# You can also use wget
curl -X POST https://api.yamalpay.io/v1/recurrents/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' \
  -d '{
    "amount": 10,
    "currency": "USD"
  }'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}
data = {
  "amount": 10,
  "currency": "USD"
}

r = requests.post('https://api.yamalpay.io/v1/recurrents/{id}', headers=headers, json=data)

print(r.json())

POST /recurrents/{id}

Body parameter

{
  "amount": 10,
  "currency": "USD"
}

To charge a recurrent payment, you need to provide the amount and currency.

Parameters

Name Type Required Description
amount integer true Recurrent payment amount
currency Currency true Recurrent payment currency

Example responses

201 Response

{
  "id": 1
}

Responses

Status Meaning Description Schema
201 Created Successful Response PaymentResponseSchema
422 Unprocessable Entity Validation Error HTTPValidationError

Cancel Recurrent

Code samples

# You can also use wget
curl -X DELETE https://api.yamalpay.io/v1/recurrents/{id} \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>'

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.delete('https://api.yamalpay.io/v1/recurrents/{id}', headers=headers)

print(r.json())

DELETE /recurrents/{id}

Cancel a recurrent payment.

Responses

Status Meaning Description Schema
204 No Content Successful Response None
404 Not Found Not Found Error None

Payments H2H

The YamalPay H2H Payments API allows businesses to initiate payments from their accounts to another account at YamalPay for seamless and secure money transfers. This method is suitable for businesses that require a convenient and efficient way to make transactions between different accounts.

Get available Payment Services

Code samples

# You can also use wget
curl -X GET https://api.yamalpay.io/v1/payments/{id}/services \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.get('https://api.yamalpay.io/v1/payments/{id}/services', headers=headers)

print(r.json())

GET /accounts/{id}/services

Get all payment services for the Payment.

Parameters

Example responses

200 Response

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "H2H Turkey",
      "type": "h2h",
      "logo_url": "https://example.com",
      "min_amount": 100,
      "max_amount": 1000000,
      "is_test_mode": true
    }
  ],
  "total": 1,
  "page": 1,
  "size": 5,
  "pages": 1
}

Responses

Status Meaning Description Schema
200 OK Successful Response Page_PaymentServiceResponseSchema_
422 Unprocessable Entity Validation Error HTTPValidationError

Get available H2H Banks

Code samples

# You can also use wget
curl -X GET https://api.yamalpay.io/v1/payments/{id}/services/p2p/{aps_id}/banks \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.get('https://api.yamalpay.io/v1/payments/{id}/services/p2p/{aps_id}/banks', headers=headers)

print(r.json())

GET /payments/{id}/services/p2p/{aps_id}/banks

Parameters

Name In Type Required Description
aps_id path string true none
id path string true none
search query any false none
page query integer false none
size query integer false none

Example responses

200 Response

{
  "items": [
    {
      "id": 1,
      "name": "America Bank",
      "logo_url": "https://example.com/logo.png"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 5,
  "pages": 1
}

Responses

Status Meaning Description Schema
200 OK Successful Response Page_H2HBanksResponseSchema_
422 Unprocessable Entity Validation Error HTTPValidationError

Get available H2H Card

Code samples

# You can also use wget
curl -X GET https://api.yamalpay.io/v1/payments/{id}/services/p2p/{aps_id}/cards/{bank_id} \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.get('https://api.yamalpay.io/v1/payments/{id}/services/p2p/{aps_id}/cards/{bank_id}', headers=headers)

print(r.json())

GET /payments/{id}/services/p2p/{aps_id}/cards/{bank_id}

Parameters

Name In Type Required Description
aps_id path string true none
bank_id path integer true none
id path string true none

Example responses

200 Response

{
  "pan": "2202206770705601",
  "holder": "John Doe",
  "logo_url": "string"
}

Responses

Status Meaning Description Schema
200 OK Successful Response H2HCardResponseSchema
422 Unprocessable Entity Validation Error HTTPValidationError

H2H Card Paid

Code samples

# You can also use wget
curl -X GET https://api.yamalpay.io/v1/payments/{id}/services/p2p/{aps_id}/cards/{bank_id}/paid \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.get('https://api.yamalpay.io/v1/payments/{id}/services/p2p/{aps_id}/cards/{bank_id}/paid', headers=headers)

print(r.json())

GET /payments/{id}/services/p2p/{aps_id}/cards/{bank_id}/paid

Parameters

Name In Type Required Description
aps_id path string true none
bank_id path integer true none
id path string true none

Example responses

200 Response

{'status': 1}

Responses

Status Meaning Description Schema
200 OK Successful Response Inline
422 Unprocessable Entity Validation Error HTTPValidationError

Withdrawals

To request a fiat withdrawal, you create a withdrawal. You can create and view withdrawals. Withdrawals are identified by a unique code.

Statuses

Status Description
Created Withdrawal has been created
Pending Withdrawal is in processing
Approved Withdrawal has been completed successfully
Rejected Withdrawal has been rejected for some reasons

Get Withdrawals

Code samples

# You can also use wget
curl -X GET https://api.yamalpay.io/v1/withdrawals/ \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.get('https://api.yamalpay.io/v1/withdrawals/', headers = headers)

print(r.json())

GET /withdrawals/

Returns all withdrawals

Example responses

200 Response

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "code": "YJM5BAID",
      "amount": 10,
      "currency": "USD",
      "created_at": "2019-08-24T14:15:22Z",
      "timeline": [
        {
          "event": "Created",
          "created_at": "2019-08-24T14:15:22Z"
        },
        {
          "event": "Pending",
          "created_at": "2019-08-24T14:15:22Z"
        },
        {
          "event": "Approved",
          "created_at": "2019-08-24T14:15:22Z"
        },
      ],
    }
  ],
  "total": 1,
  "page": 1,
  "size": 5,
  "pages": 1
}

Responses

Status Meaning Description Schema
200 OK Successful Response Page_WithdrawalResponseSchema_

Create Withdrawal

Code samples

# You can also use wget
curl -X POST https://api.yamalpay.io/v1/withdrawals/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' \
  -d '{
    "amount": 10,
    "currency": "USD",
    "address": "4242 4242 4242 4242"
  }'


import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}
data = {
  "amount": 10,
  "currency": "USD",
  "address": "4242 4242 4242 4242"
}

r = requests.post('https://api.yamalpay.io/v1/withdrawals/', headers=headers, json=data)

print(r.json())

POST /withdrawals/

Body parameter

{
  "amount": 10,
  "currency": "USD",
  "address": "4242 4242 4242 4242"
}

To request a withdrawal you have to create a withdrawal.

Parameters

Name Type Required Description
amount integer true Withdrawal amount
currency Currency true Withdrawal currency
address string(pan) true Card number or deposit number

Example responses

201 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "amount": 10,
  "currency": "USD",
  "address": "4242 4242 4242 4242"
  "created_at": "2019-08-24T14:15:22Z",
  "timeline": [
    {
      "event": "Created",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Responses

Status Meaning Description Schema
201 Created Successful Response WithdrawalResponseSchema
422 Unprocessable Entity Validation Error HTTPValidationError

Show Withdrawal

Code samples

# You can also use wget
curl -X GET https://api.yamalpay.io/v1/withdrawals/{id}/ \
  -H 'Accept: application/json' \
  -H 'x-api-key: <Your API Key>' 


import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.get('https://api.yamalpay.io/v1/withdrawals/{id}/', headers = headers)

print(r.json())

GET /withdrawals/{id}/

Retrieves the details of a withdrawal that has been previously created. Supply the unique withdrawal code that was returned when the withdrawal was created. This information is also returned when a withdrawal is first created.

Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "amount": 10,
  "currency": "USD",
  "created_at": "2019-08-24T14:15:22Z",
  "timeline": [
    {
      "event": "Created",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Successful Response WithdrawalResponseSchema
404 Not Found Not Found Error None

Schemas

Currency

"USD"

Currency

Properties

Name Type Description
Currency string Available Currencies.

Enumerated Values

Property Value
Currency USD
Currency EUR
Currency RUB
Currency UAH
Currency KZT
Currency AZN
Currency TRY

HTTPValidationError

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

HTTPValidationError

Properties

Name Type Required Description
detail [ValidationError] false none

H2HCardResponseSchema

{
  "pan": "2202206770705601",
  "holder": "John Doe",
  "logo_url": "string"
}

H2HCardResponseSchema

Properties

Name Type Description
pan string none
holder string none
logo_url string none

Page_PaymentResponseSchema_

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "resource": "payment",
      "code": "YJM5BAID",
      "name": "Product",
      "description": "The best Product",
      "amount": 10,
      "currency": "USD",
      "hosted_url": "https://pay.yamalpay.io/payments/YJM5BAID",
      "success_url": "https://example.com",
      "fail_url": "https://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "confirmed_at": "2019-08-24T14:15:22Z",
      "transactions": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "amount": 10,
          "currency": "USD",
          "status": "Approved",
          "account": "Shop",
          "payment_service": "H2H Ru",
          "payment_service_type": "bankcard",
          "created_at": "2019-08-24T14:15:22Z"
        }
      ],
      "timeline": [
        {
          "event": "Opened",
          "created_at": "2019-08-24T14:15:22Z"
        },
        {
          "event": "Pending",
          "created_at": "2019-08-24T14:15:22Z"
        },
        {
          "event": "Approved",
          "created_at": "2019-08-24T14:15:22Z"
        },
      ],
      "metadata": {
        "user_id": 123
      },
      "is_recurring": false,
      "recurrent": {
        "id": 1
      }
    }
  ],
  "total": 1,
  "page": 1,
  "size": 5,
  "pages": 1
}

Page[PaymentResponseSchema]

Properties

Name Type Description
items [PaymentResponseSchema] Payments list
total integer Total objects in query
page integer Page of query
size integer Number of results per call. Accepted values: 0 - 100. Default 50

Page_PaymentServiceResponseSchema_

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "H2H Turkey",
      "type": "h2h",
      "logo_url": "https://example.com/logo.png",
      "min_amount": 100,
      "max_amount": 100000,
      "is_test_mode": true
    }
  ],
  "total": 1,
  "page": 1,
  "size": 5,
  "pages": 1
}

Page[PaymentServiceResponseSchema]

Properties

Name Type Required Restrictions Description
items [PaymentServiceResponseSchema] true none none
total integer true none none
page any true none none

PaymentPayloadSchema

{
  "name": "Product",
  "description": "The best Product",
  "amount": 10,
  "currency": "USD",
  "is_recurring": false,
  "metadata": {
    "user_id": 123
  },
  "success_url": "https://google.com",
  "fail_url": "https://google.com",
  "ttl": 3600
}

PaymentPayloadSchema

Properties

Name Type Required Description
name string (255) true Payment name
description string (255) false More detailed description of the payment
amount integer true Payment amount
currency Currency true Payment currency
is_recurring boolean false Recurring payment
metadata object false Developer defined key value pairs
success_url string(uri) false Redirect URL after successful payment
fail_url string(uri) false Redirect URL after cancelled payment
ttl integer false Time to live in seconds

Page_WithdrawalResponseSchema_

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "code": "YJM5BAID",
      "amount": 10,
      "currency": "USD",
      "address": "4242 4242 4242 4242",
      "created_at": "2019-08-24T14:15:22Z",
      "timeline": [
        {
          "event": "Created",
          "created_at": "2019-08-24T14:15:22Z"
        },
        {
          "event": "Pending",
          "created_at": "2019-08-24T14:15:22Z"
        },
        {
          "event": "Approved",
          "created_at": "2019-08-24T14:15:22Z"
        },
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "size": 5,
  "pages": 1
}

Page[WithdrawalResponseSchema]

Properties

Name Type Description
items [WithdrawalResponseSchema] Withdrawals list
total integer Total objects in query
page integer Page of query
size integer Number of results per call. Accepted values: 0 - 100. Default 50

PaymentResponseSchema

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "resource": "payment",
  "code": "YJM5BAID",
  "name": "Product",
  "description": "The best Product",
  "amount": 10,
  "currency": "USD",
  "hosted_url": "https://pay.yamalpay.io/payments/YJM5BAID",
  "success_url": "https://example.com",
  "fail_url": "https://example.com",
  "created_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "confirmed_at": "2019-08-24T14:15:22Z",
  "transactions": [],
  "timeline": [
    {
      "event": "Opened",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "metadata": {
    "user_id": 123
  },
  "is_recurring": false,
  "recurrent": {
    "id": 1
  }
}

PaymentResponseSchema

Properties

Name Type Description
id string(uuid) Payment ID
resource string Resource name
code string Payment code
name string Payment name
description string Payment description
amount int Payment amount
currency Currency Payment currency
hosted_url string(uri) Hosted url of Payment page
success_url string(uri) Redirect url after successful payment
fail_url string(uri) Redirect url after cancelled payment
created_at string(date-time) Time of creating
expires_at string(date-time) Time of expiring
confirmed_at string(date-time) Time of confirmation
timeline [StatusResponseSchema] Status history
metadata object Key value pairs
transactions [TransactionInResponseSchema] Payment transactions
is_recurring boolean Recurring payment
recurrent object Recurrent payment

PaymentServiceResponseSchema

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "H2H Turkey",
  "type": "h2h",
  "logo_url": "https://example.com/logo.png",
  "min_amount": 100,
  "max_amount": 100000,
  "is_test_mode": true
}

PaymentServiceResponseSchema

Properties

Name Type Required Restrictions Description
id string(uuid) true none none
name string true none none
type string true none none
logo_url any true none none
min_amount number true none none
max_amount number true none none
is_test_mode boolean true none none

StatusResponseSchema

{
  "status": "Completed",
  "created_at": "2019-08-24T14:15:22Z"
}

StatusResponseSchema

Properties

Name Type Description
status string Status name
created_at string(date-time) Time of creating

TransactionInResponseSchema

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "amount": 10,
  "currency": "USD",
  "status": "Approved",
  "account": "Shop",
  "payment_service": "H2H Ru",
  "payment_service_type": "bankcard",
  "created_at": "2019-08-24T14:15:22Z"
}

TransactionInResponseSchema

Properties

Name Type Description
amount integer none
currency Currency none
status string none
account string none
payment_service string none
payment_service_type string none
created_at string(date-time) none

ValidationError

{
  "loc": [
    "string"
  ],
  "msg": "string",
  "type": "string"
}

ValidationError

Properties

Name Type Description
loc [anyOf] none

anyOf

Name Type Description
» anonymous string none

or

Name Type escription
» anonymous integer none

continued

Name Type Description
msg string Error message
type string Error type

WebhookEvent

"payment.completed"

WebhookEvent

Properties

Name Type Description
WebhookEvent string Available Webhook events.

Enumerated Values

Property Value
WebhookEvent payment.created
WebhookEvent payment.completed
WebhookEvent payment.unresolved
WebhookEvent payment.resolved
WebhookEvent payment.expired
WebhookEvent payment.closed
WebhookEvent transaction.refunded
WebhookEvent withdrawal.completed

WithdrawalResponseSchema

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "code": "YJM5BAID",
  "amount": 10,
  "currency": "USD",
  "address": "4242 4242 4242 4242",
  "created_at": "2019-08-24T14:15:22Z",
  "timeline": [
    {
      "event": "Created",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

WithdrawalResponseSchema

Properties

Name Type Description
id string(uuid) Withdrawal ID
code string Withdrawal code
amount int Withdrawal amount
currency Currency Withdrawal currency
address string Card number or deposit number
created_at string(date-time) Time of creating
timeline [StatusResponseSchema] Status history
Shell Python