Tworzenie faktury

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

Wniosek

Parametry zapytania

NazwaTyp parametruDomyślna wartośćDefinicja
amount*string-Suma do zapłaty.Jeśli w kwoty są grosze, wyślij je z separatorem „”.
Przykład: 10.28
currency*string-Kod waluty
order_id*stringmin: 1max: 100alpha_dash-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.
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_currencystring-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.
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
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 Cryptomus i otrzymasz dochód z ich obrotu.
discount_percentintegermin: -99max: 90nullLiczby 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: 100alpha_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

Domyślna wartość

null

Definicja

Kod sieci Blockchain

Typ parametru

stringmin: 6max: 255url

Domyślna wartość

null

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

Domyślna wartość

null

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

Domyślna wartość

null

Definicja

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

Typ parametru

boolean

Domyślna wartość

true

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

Domyślna wartość

3600

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

Domyślna wartość

0

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

Domyślna wartość

0

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

Domyślna wartość

null

Definicja

Dodatkowe informacje dla Ciebie (nie pokazane klientowi)

Typ parametru

array

Domyślna wartość

Uż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.

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

Domyślna wartość

null

Definicja

Lista wykluczonych walut do płatności Struktura

Typ parametru

string

Domyślna wartość

null

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 Cryptomus i otrzymasz dochód z ich obrotu.

Typ parametru

integermin: -99max: 90

Domyślna wartość

null

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

Domyślna wartość

false

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"
}'
Kopia

Odpowiedź

Parametry odpowiedzi

NazwaTyp parametruDefinicja
uuidstringFaktura uuid
order_idstring|nullZamów identyfikator w twoim systemie
amountstringIlość faktury
payment_amountstring|nullKwota zapłacona przez klienta
payment_amount_usdstring|nullKwota faktycznie opłacona przez klienta w USD
payer_amountstring|nullKwota w payer_currency , którą klient musi zapłacić, w tym zniżka lub dodatkowa prowizja.
payer_amount_exchange_ratestring|nullKurs wymiany zastosowany w momencie realizacji płatności
discount_percentinteger|nullProcent rabatu lub dodatkowa prowizja, która została przekazana w parametrach żądania
discountstringRzeczywista 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_currencystring|nullWaluta, w której klient musi dokonać płatności.
currencystringKod waluty faktury
commentsstring|nullKomentarz
merchant_amountstring|nullKwota w kryptografii, która zostanie przypisana do twojego salda. Jeśli nie zostanie określona, ​​wartość nie zostanie określona, ​​wartość będzie null.
networkstring|nullKod sieci Blockchain
addressstring|nullAdres portfela do płatności
fromstring|nullAdres portfela, z którego dokonano płatności
txidstring|nullHash transakcji
payment_statusstringStatus płatności Wszystkie statusy płatności
urlstringStrona płatności URL
expired_atinteger|nullZnacznik czasu wygaśnięcia faktury
statusstringStatus płatności Wszystkie statusy płatności
is_finalbooleanCzy faktura jest sfinalizowana.Po sfinalizowaniu faktury nie można zapłacić faktury (jest ona opłacana lub wygasła)
additional_datastring|nullDodatkowe informacje
created_atstring|nullData utworzenia faktury. Strefa czasowa to UTC+3
updated_atstring|nullOstatnia faktura zaktualizowana data. Strefa czasowa to UTC+3
commissionstring|nullKwota Komisji Cryptomus
address_qr_codestring|nullKod QR adresu
convertInformacje o walucie, do której płatność zostanie automatycznie przekonwertowana. Konwersja odbywa się z płatnika_currency do USDTObecny, jeśli przekazano convert_currency_code
convert.to_currencystringKod waluty, do którego płatność zostanie przekonwertowana
convert.commissionstringOpłata za konwersję
convert.ratestring|nullWspółczynnik konwersji
convert.amountstring|nullKwota konwersji w to_currency, która została dodana do równowagi sprzedawcy, przy odjęciu wszystkich prowizji.
convert_fromInformacje o walucie, z której dokonano nieprawidłowej płatnościObecny, jeśli płatność jest nieprawidłowa
convert_from.from_currencystringZ waluty
convert_from.from_amountstring|nullKwota od
convert_from.from_networkstring|nullKod sieci Blockchain

Typ parametru

string

Definicja

Faktura uuid

Typ parametru

string|null

Definicja

Zamów identyfikator w twoim systemie

Typ parametru

string

Definicja

Ilość faktury

Typ parametru

string|null

Definicja

Kwota zapłacona przez klienta

Typ parametru

string|null

Definicja

Kwota faktycznie opłacona przez klienta w USD

Typ parametru

string|null

Definicja

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

Typ parametru

string|null

Definicja

Kurs wymiany zastosowany w momencie realizacji płatności

Typ parametru

integer|null

Definicja

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

Typ parametru

string

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

Typ parametru

string|null

Definicja

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

Typ parametru

string

Definicja

Kod waluty faktury

Typ parametru

string|null

Definicja

Komentarz

Typ parametru

string|null

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.

Typ parametru

string|null

Definicja

Kod sieci Blockchain

Typ parametru

string|null

Definicja

Adres portfela do płatności

Typ parametru

string|null

Definicja

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

Typ parametru

string|null

Definicja

Hash transakcji

Typ parametru

string

Definicja

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

Typ parametru

string

Definicja

Strona płatności URL

Typ parametru

integer|null

Definicja

Znacznik czasu wygaśnięcia faktury

Typ parametru

string

Definicja

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

Typ parametru

boolean

Definicja

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

Typ parametru

string|null

Definicja

Dodatkowe informacje

Typ parametru

string|null

Definicja

Data utworzenia faktury. Strefa czasowa to UTC+3

Typ parametru

string|null

Definicja

Ostatnia faktura zaktualizowana data. Strefa czasowa to UTC+3

Typ parametru

string|null

Definicja

Kwota Komisji Cryptomus

Typ parametru

string|null

Definicja

Kod QR adresu

Definicja

Informacje o walucie, do której płatność zostanie automatycznie przekonwertowana. Konwersja odbywa się z płatnika_currency do USDTObecny, jeśli przekazano convert_currency_code

Typ parametru

string

Definicja

Kod waluty, do którego płatność zostanie przekonwertowana

Typ parametru

string

Definicja

Opłata za konwersję

Typ parametru

string|null

Definicja

Współczynnik konwersji

Typ parametru

string|null

Definicja

Kwota konwersji w to_currency, która została dodana do równowagi sprzedawcy, przy odjęciu wszystkich prowizji.

Definicja

Informacje o walucie, z której dokonano nieprawidłowej płatnościObecny, jeśli płatność jest nieprawidłowa

Typ parametru

string

Definicja

Z waluty

Typ parametru

string|null

Definicja

Kwota od

Typ parametru

string|null

Definicja

Kod sieci Blockchain

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		"payment_amount_usd": null,
9		"payer_amount": null,
10		"payer_amount_exchange_rate": null,
11		"discount_percent": null,
12		"discount": "0.00000000",
13		"payer_currency": null,
14		"currency": "USD",
15		"comments": null,
16		"merchant_amount": null,
17		"network": null,
18		"address": null,
19		"from": null,
20		"txid": null,
21		"payment_status": "check",
22		"url": "https://pay.cryptomus.com/pay/26109ba0-b05b-4ee0-93d1-fd62c822ce95",
23		"expired_at": 1689098133,
24		"status": "check",
25		"is_final": false,
26		"additional_data": null,
27		"created_at": "2023-07-11T20:23:52+03:00",
28		"updated_at": "2023-07-11T21:24:17+03:00",
29		"commission": null,
30		"address_qr_code": null
31	}
32}
Kopia

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}
Kopia

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}
Kopia

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}
Kopia

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}
Kopia

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}
Kopia

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}
Kopia

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}
Kopia

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


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

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}
Kopia

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}
Kopia

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}
Kopia

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


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

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}
Kopia

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}
Kopia

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}
Kopia

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}
Kopia


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


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

Wewnętrzny błąd serwera

kod : 500

przykładowe odpowiedzi:


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