Tworzenie faktury

post
https://api.cryptomus.com/v1/payment
KOPIUJ

Wniosek

Parametry zapytania

NazwaTyp parametruDomyślna wartośćDefinicja
amount*stringSuma do zapłaty.Jeśli w kwoty są grosze, wyślij je z separatorem „”.
Przykład: 10.28
currency*stringKod waluty
order_id*stringmin: 1max: 128alpha_dashZamów identyfikator w twoim systemieParametr powinien być łańcuchem składającym się z znaków alfabetycznych, liczb, podkreśleń i dystansów. Nie powinien zawierać żadnych przestrzeni ani znaków specjalnych. order_id musi być unikalny na faktach handlowych/statycznych portfelach/płatnościach nawrotówKiedy znajdziemy istniejącą fakturę z order_id , zwracamy jego szczegóły, nie zostanie utworzona nowa faktura.
networkstringnullKod sieci Blockchain
url_returnstringmin: 6max: 255urlnullPrzed zapłaceniem użytkownik może kliknąć przycisk w formularzu płatności i wrócić do strony sklepu w tym adresie URL.
url_successstringmin: 6max: 255urlnullPo udanej płatności użytkownik może kliknąć przycisk w formularzu płatności i wrócić do tego adresu URL.
url_callbackstringmin: 6max: 255urlnullURL, do którego Webhooks ze statusem płatności zostaną wysłane
is_payment_multiplebooleantrueCzy użytkownik może zapłacić pozostałą kwotę. Jest to przydatne, gdy użytkownik nie zapłacił całej kwoty faktury za jedną transakcję i chcesz pozwolić mu zapłacić do pełnej kwoty. Jeśli wyłączysz tę funkcję, faktura zakończy się po otrzymaniu pierwszej płatności i otrzymasz środki na saldo.
lifetimeintegermin: 300max: 432003600Żywotność wydanej faktury (w sekundach)
to_currencystringParametr służy do określenia docelowej waluty do konwersji kwoty faktury. Podczas tworzenia faktury podajesz kwotę i walutę, a interfejs API przekonwertuje tę kwotę na równoważną wartość w to_currency.Na przykład, aby utworzyć fakturę dla 20 USD w Bitcoin:
amount: 20
currency: USD
to_currency : BTC
API przekonwertuje kwotę 20 USD na równoważny w BTC na podstawie bieżącego kursu walutowego, a użytkownik zapłaci w BTC to_currency powinien być zawsze kodem kryptowaluty, a nie kodem waluty fiat.
subtractintegermin: 0max: 1000Procent Komisji Płatności naliczonej klientowiJeśli masz stawkę 1%, jeśli utworzysz fakturę za 100 USDT z odejmowaniem = 100 (klient płaci 100% prowizji), klient będzie musiał zapłacić 101 USDT.
accuracy_payment_percentnumericmin: 0max: 50Dopuszczalna niedokładność płatności.Na przykład, jeśli zdasz wartość 5, faktura zostanie oznaczona jako opłacona, nawet jeśli klient zapłacił tylko 95% kwoty.Rzeczywista kwota płatności zostanie przypisana na saldo
additional_datastringmax: 255nullDodatkowe informacje dla Ciebie (nie pokazane klientowi)
currenciesarrayUżywana jest tablica dostępnych walut z ustawień sprzedawcy (jeśli parametr nie jest ustawiony, domyślnie używane są wszystkie obsługiwane kryptowaluty).Dostępne waluty są ustawione w sekcji Ustawienia handlowe.Lista dozwolonych walut do płatności. Jest to przydatne, jeśli chcesz ograniczyć listę monet, których klienci mogą użyć do płacenia faktur. Struktura
except_currenciesarraynullLista wykluczonych walut do płatności Struktura
course_sourcestringmin: 4max: 20Dostępne wartościBinanceBinanceP2PExmoKucoinGarantexioJeśli nie jest przekazane, wykorzystywane są kursy wymiany kryptomus.Usługa, z której kursy walut są pobierane w celu konwersji we fakturze.
from_referral_codestringnullKupiec, który składa żądanie, łączy się z poleceniem według kodu.Na przykład jesteś aplikacją, która generuje faktury za pośrednictwem Cryptomus API, a Twoi klienci to inne sklepy.
Wprowadzają swój klucz API i identyfikator handlowy w aplikacji, a ty wysyłasz żądania z ich poświadczeniami i przekazując kod polecający.
W ten sposób Twoi klienci stają się poleceniami na koncie kryptomus i otrzymasz dochód z ich obrotu.
discount_percentintegermin: -99max: 100nullLiczby dodatnie:
pozwala ustawić zniżkę.
Aby ustawić 5% rabatu na płatność, powinieneś przekazać wartość: 5
Liczby ujemne:
pozwala ustawić niestandardową dodatkową prowizję.
Aby ustalić dodatkową prowizję na poziomie 10% za płatność, powinieneś przekazać wartość: -10Procent rabatu podczas tworzenia faktury jest brany pod uwagę tylko wtedy, gdy faktura ma określoną kryptowalutę.
is_refreshbooleanfalseKorzystając z tego parametru, możesz zaktualizować żywotność i uzyskać nowy adres faktury, jeśli żywotność wygasła.Aby to zrobić, musisz przekazać wszystkie wymagane parametry, a faktura z przekazaną order_id zostanie odświeżona.Tylko address , payment_status i expired_at . Żadne inne pola nie są zmieniane, niezależnie od przekazanych parametrów.

Typ parametru

string

Definicja

Suma do zapłaty.Jeśli w kwoty są grosze, wyślij je z separatorem „”.
Przykład: 10.28

Typ parametru

string

Definicja

Kod waluty

Typ parametru

stringmin: 1max: 128alpha_dash

Definicja

Zamów identyfikator w twoim systemieParametr powinien być łańcuchem składającym się z znaków alfabetycznych, liczb, podkreśleń i dystansów. Nie powinien zawierać żadnych przestrzeni ani znaków specjalnych. order_id musi być unikalny na faktach handlowych/statycznych portfelach/płatnościach nawrotówKiedy znajdziemy istniejącą fakturę z order_id , zwracamy jego szczegóły, nie zostanie utworzona nowa faktura.

Typ parametru

string

Definicja

Kod sieci Blockchain

Typ parametru

stringmin: 6max: 255url

Definicja

Przed zapłaceniem użytkownik może kliknąć przycisk w formularzu płatności i wrócić do strony sklepu w tym adresie URL.

Typ parametru

stringmin: 6max: 255url

Definicja

Po udanej płatności użytkownik może kliknąć przycisk w formularzu płatności i wrócić do tego adresu URL.

Typ parametru

stringmin: 6max: 255url

Definicja

URL, do którego Webhooks ze statusem płatności zostaną wysłane

Typ parametru

boolean

Definicja

Czy użytkownik może zapłacić pozostałą kwotę. Jest to przydatne, gdy użytkownik nie zapłacił całej kwoty faktury za jedną transakcję i chcesz pozwolić mu zapłacić do pełnej kwoty. Jeśli wyłączysz tę funkcję, faktura zakończy się po otrzymaniu pierwszej płatności i otrzymasz środki na saldo.

Typ parametru

integermin: 300max: 43200

Definicja

Żywotność wydanej faktury (w sekundach)

Typ parametru

string

Definicja

Parametr służy do określenia docelowej waluty do konwersji kwoty faktury. Podczas tworzenia faktury podajesz kwotę i walutę, a interfejs API przekonwertuje tę kwotę na równoważną wartość w to_currency.Na przykład, aby utworzyć fakturę dla 20 USD w Bitcoin:
amount: 20
currency: USD
to_currency : BTC
API przekonwertuje kwotę 20 USD na równoważny w BTC na podstawie bieżącego kursu walutowego, a użytkownik zapłaci w BTC to_currency powinien być zawsze kodem kryptowaluty, a nie kodem waluty fiat.

Typ parametru

integermin: 0max: 100

Definicja

Procent Komisji Płatności naliczonej klientowiJeśli masz stawkę 1%, jeśli utworzysz fakturę za 100 USDT z odejmowaniem = 100 (klient płaci 100% prowizji), klient będzie musiał zapłacić 101 USDT.

Typ parametru

numericmin: 0max: 5

Definicja

Dopuszczalna niedokładność płatności.Na przykład, jeśli zdasz wartość 5, faktura zostanie oznaczona jako opłacona, nawet jeśli klient zapłacił tylko 95% kwoty.Rzeczywista kwota płatności zostanie przypisana na saldo

Typ parametru

stringmax: 255

Definicja

Dodatkowe informacje dla Ciebie (nie pokazane klientowi)

Typ parametru

array

Definicja

Lista dozwolonych walut do płatności. Jest to przydatne, jeśli chcesz ograniczyć listę monet, których klienci mogą użyć do płacenia faktur. Struktura

Typ parametru

array

Definicja

Lista wykluczonych walut do płatności Struktura

Typ parametru

stringmin: 4max: 20
Dostępne wartości
- Binance- BinanceP2P- Exmo- Kucoin- Garantexio

Definicja

Usługa, z której kursy walut są pobierane w celu konwersji we fakturze.

Typ parametru

string

Definicja

Kupiec, który składa żądanie, łączy się z poleceniem według kodu.Na przykład jesteś aplikacją, która generuje faktury za pośrednictwem Cryptomus API, a Twoi klienci to inne sklepy.
Wprowadzają swój klucz API i identyfikator handlowy w aplikacji, a ty wysyłasz żądania z ich poświadczeniami i przekazując kod polecający.
W ten sposób Twoi klienci stają się poleceniami na koncie kryptomus i otrzymasz dochód z ich obrotu.

Typ parametru

integermin: -99max: 100

Definicja

Liczby dodatnie:
pozwala ustawić zniżkę.
Aby ustawić 5% rabatu na płatność, powinieneś przekazać wartość: 5
Liczby ujemne:
pozwala ustawić niestandardową dodatkową prowizję.
Aby ustalić dodatkową prowizję na poziomie 10% za płatność, powinieneś przekazać wartość: -10Procent rabatu podczas tworzenia faktury jest brany pod uwagę tylko wtedy, gdy faktura ma określoną kryptowalutę.

Typ parametru

boolean

Definicja

Korzystając z tego parametru, możesz zaktualizować żywotność i uzyskać nowy adres faktury, jeśli żywotność wygasła.Aby to zrobić, musisz przekazać wszystkie wymagane parametry, a faktura z przekazaną order_id zostanie odświeżona.Tylko address , payment_status i expired_at . Żadne inne pola nie są zmieniane, niezależnie od przekazanych parametrów.

* - obowiązkowy parametr

Struktura Waluty

NazwaDefinicja
currency*Kod waluty
networkKod sieci Blockchain

Definicja

Kod waluty

Definicja

Kod sieci Blockchain

* - obowiązkowy parametr

Struktura except_currencies

NazwaDefinicja
currency*Kod waluty
networkKod sieci Blockchain

Definicja

Kod waluty

Definicja

Kod sieci Blockchain

* - obowiązkowy parametr

Faktura będzie miała konkretną kryptowalutę i adres w momencie tworzenia tylko wtedy, gdy waluta lub parametr to_currency jest kryptowalutą, a parametr sieci jest przekazywany (lub kryptowaluta ma tylko jedną sieć, na przykład BTC).

Przykład żądania

Poniżej znajduje się przykładowy przykład z minimalną wymaganą liczbą parametrów. W takim przypadku faktura zostanie utworzona z walutą Fiat. Na stronie płatności użytkownik będzie mógł wybrać kryptowalutę i sieć, aby zapłacić ten rachunek.


curl https://api.cryptomus.com/v1/payment \
-X POST \
-H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
-H 'sign: fe99035f86fa436181717b302b95bacff1' \
-H 'Content-Type: application/json' \
-d '{
	"amount": "15",
	"currency": "USD",
	"order_id": "1"
}'
KOPIUJ

Odpowiedź

Parametry odpowiedzi

NazwaDefinicja
uuidFaktura uuid
order_idZamów identyfikator w twoim systemie
amountIlość faktury
payment_amountKwota zapłacona przez klienta
payer_amountKwota w payer_currency , którą klient musi zapłacić, w tym zniżka lub dodatkowa prowizja.
discount_percentProcent rabatu lub dodatkowa prowizja, która została przekazana w parametrach żądania
discountRzeczywista kwota rabatu lub dodatkowej prowizji w kryptowalucie.Na przykład, jeśli kwota faktury wynosi 15 USDT, a rabat_percent wynosi -5, wartość rabatowa wyniesie -0,75tj. amount + discount = payer_amount
payer_currencyWaluta, w której klient musi dokonać płatności.
currencyKod waluty faktury
merchant_amountKwota w kryptografii, która zostanie przypisana do twojego salda. Jeśli nie zostanie określona, ​​wartość nie zostanie określona, ​​wartość będzie null.
networkKod sieci Blockchain
addressAdres portfela do płatności
fromAdres portfela, z którego dokonano płatności
txidHash transakcji
payment_statusStatus płatności Wszystkie statusy płatności
urlStrona płatności URL
expired_atZnacznik czasu wygaśnięcia faktury
is_finalCzy faktura jest sfinalizowana.Po sfinalizowaniu faktury nie można zapłacić faktury (jest ona opłacana lub wygasła)
additional_dataDodatkowe informacje
created_atData utworzenia faktury. Strefa czasowa to UTC+3
updated_atOstatnia faktura zaktualizowana data. Strefa czasowa to UTC+3

Definicja

Faktura uuid

Definicja

Zamów identyfikator w twoim systemie

Definicja

Ilość faktury

Definicja

Kwota zapłacona przez klienta

Definicja

Kwota w payer_currency , którą klient musi zapłacić, w tym zniżka lub dodatkowa prowizja.

Definicja

Procent rabatu lub dodatkowa prowizja, która została przekazana w parametrach żądania

Definicja

Rzeczywista kwota rabatu lub dodatkowej prowizji w kryptowalucie.Na przykład, jeśli kwota faktury wynosi 15 USDT, a rabat_percent wynosi -5, wartość rabatowa wyniesie -0,75tj. amount + discount = payer_amount

Definicja

Waluta, w której klient musi dokonać płatności.

Definicja

Kod waluty faktury

Definicja

Kwota w kryptografii, która zostanie przypisana do twojego salda. Jeśli nie zostanie określona, ​​wartość nie zostanie określona, ​​wartość będzie null.

Definicja

Kod sieci Blockchain

Definicja

Adres portfela do płatności

Definicja

Adres portfela, z którego dokonano płatności

Definicja

Hash transakcji

Definicja

Status płatności Wszystkie statusy płatności

Definicja

Strona płatności URL

Definicja

Znacznik czasu wygaśnięcia faktury

Definicja

Czy faktura jest sfinalizowana.Po sfinalizowaniu faktury nie można zapłacić faktury (jest ona opłacana lub wygasła)

Definicja

Dodatkowe informacje

Definicja

Data utworzenia faktury. Strefa czasowa to UTC+3

Definicja

Ostatnia faktura zaktualizowana data. Strefa czasowa to UTC+3

Przykład odpowiedzi


1{
2	"state": 0,
3	"result": {
4		"uuid": "26109ba0-b05b-4ee0-93d1-fd62c822ce95",
5		"order_id": "1",
6		"amount": "15.00",
7		"payment_amount": null,
8		"payer_amount": null,
9		"discount_percent": null,
10		"discount": "0.00000000",
11		"payer_currency": null,
12		"currency": "USD",
13		"merchant_amount": null,
14		"network": null,
15		"address": null,
16		"from": null,
17		"txid": null,
18		"payment_status": "check",
19		"url": "https://pay.cryptomus.com/pay/26109ba0-b05b-4ee0-93d1-fd62c822ce95",
20		"expired_at": 1689098133,
21		"status": "check",
22		"is_final": false,
23		"additional_data": null,
24		"created_at": "2023-07-11T20:23:52+03:00",
25		"updated_at": "2023-07-11T21:24:17+03:00"
26	}
27}
KOPIUJ

Więcej przykładów

Poproś o dane, aby utworzyć fakturę dla 20 USDT w sieci Tron. Faktura będzie miała adres w momencie tworzenia.


1{
2	"amount": "20",
3	"currency": "USDT",
4	"order_id": "1",
5	"network": "tron"
6}
KOPIUJ

Poproś o dane, aby utworzyć fakturę dla 25 USD i pozwolić klientom płacić tylko przez USDT w dowolnej sieci.


1{
2	"amount": "25",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "USDT"
6}
KOPIUJ

Poproś o dane, aby utworzyć fakturę dla 25 USD i pozwolić klientom płacić tylko przez USDT w sieci Tron. Faktura będzie miała adres w momencie tworzenia.


1{
2	"amount": "25",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "USDT",
6	"network": "tron"
7}
KOPIUJ

Poproś o dane, aby utworzyć fakturę dla 20 USDT i umożliwić klientom płacenie we wszystkich dostępnych sieciach


1{
2	"amount": "20",
3	"currency": "USDT",
4	"order_id": "1"
5}
KOPIUJ

Poproś o dane, aby utworzyć fakturę za 20 USD i pozwolić klientom płacić tylko w Bitcoin. Faktura będzie miała adres w momencie tworzenia.


1{
2	"amount": "20",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "BTC"
6}
KOPIUJ

Poproś o dane, aby utworzyć fakturę dla 0,5 BTC i umożliwić klientom płacenie tylko w Bitcoin. Faktura będzie miała adres w momencie tworzenia.


1{
2	"amount": "0.5",
3	"currency": "BTC",
4	"order_id": "1"
5}
KOPIUJ

Możliwe błędy

Błędy walidacji

kod : 422

Przykładowe odpowiedzi:

Jeśli wymagany jest jakiś parametr i nie jest przekazany:


1{
2	"state": 1,
3	"errors": {
4		"amount": ["validation.required"]
5	}
6}
KOPIUJ

Jeśli podałeś kod sieciowy, który nie jest obsługiwany


1{
2    "state": 1,
3    "message": "The network was not found"
4}
KOPIUJ

Jeśli nie obsługujemy kodu walutowego, który podałeś w parametrze waluty :


1{
2    "state": 1,
3    "message": "The currency was not found"
4}
KOPIUJ

Jeśli twoje płatności są zablokowane. W takim przypadku musisz skontaktować się z wsparciem.


1{
2    "state": 1,
3    "message": "You are forbidden"
4}
KOPIUJ

Payments.If we don’t find the payment service of the currency that was passed in to_currency parameter


1{
2    "state": 1,
3    "message": "Not found service to_currency"
4}
KOPIUJ

Jeśli przypadkowo coś się dzieje podczas konwersji na to_currency :


1{
2    "state": 1,
3    "message": "Error convert to_currency"
4}
KOPIUJ

Jeśli kwota płatności jest mniejsza niż minimalna obsługiwana kwota kryptowaluty, otrzymasz ten komunikat o błędzie:


1{
2    "state": 1,
3    "message": "Minimum amount 0.5 USDT"
4}
KOPIUJ

Jeśli kwota płatności jest większa niż maksymalna obsługiwana kwota kryptowaluty, otrzymasz ten komunikat o błędzie:


1{
2    "state": 1,
3    "message": "Maximum amount 10000000 USDT"
4}
KOPIUJ

Jeśli nie będziesz mieć aktywnego portfela handlowego z kryptowalutą płatności, otrzymasz ten błąd:


1{
2    "state": 1,
3    "message": "Wallet not found"
4}
KOPIUJ

Jeśli nastąpi praca techniczna, a płatność jest tymczasowo niedostępna, możesz otrzymać te komunikaty o błędach:


1{
2    "state": 1,
3    "message": "Gateway error"
4}
KOPIUJ


1{
2    "state": 1,
3    "message": "The terminal was not found"
4}
KOPIUJ


1{
2    "state": 1,
3    "message": "Server error"
4}
KOPIUJ

Wewnętrzny błąd serwera

kod : 500

Przykładowe odpowiedzi:


1{
2	"message": "Server error, #1",
3	"code": 500,
4	"error": null
5}
KOPIUJ