Tworzenie faktury
Wniosek
Parametry zapytania
| Nazwa | Typ parametru | Domyś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. |
| network | string | null | Kod sieci Blockchain |
| url_return | stringmin: 6max: 255url | null | Przed zapłaceniem użytkownik może kliknąć przycisk w formularzu płatności i wrócić do strony sklepu w tym adresie URL. |
| url_success | stringmin: 6max: 255url | null | Po udanej płatności użytkownik może kliknąć przycisk w formularzu płatności i wrócić do tego adresu URL. |
| url_callback | stringmin: 6max: 255url | null | URL, do którego webhooks ze statusem płatności zostaną wysłane |
| is_payment_multiple | boolean | true | 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. |
| lifetime | integermin: 300max: 43200 | 3600 | Żywotność wydanej faktury (w sekundach) |
| to_currency | string | - | 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 : BTCAPI 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. |
| subtract | integermin: 0max: 100 | 0 | 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. |
| accuracy_payment_percent | numericmin: 0max: 5 | 0 | 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 |
| additional_data | stringmax: 255 | null | Dodatkowe informacje dla Ciebie (nie pokazane klientowi) |
| currencies | array | 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. | 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_currencies | array | null | Lista wykluczonych walut do płatności Struktura |
| from_referral_code | string | null | 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. |
| discount_percent | integermin: -99max: 90 | null | Liczby dodatnie: pozwala ustawić zniżkę. Aby ustawić 5% rabatu na płatność, powinieneś przekazać wartość: 5Liczby 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_refresh | boolean | false | 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. |
Typ parametru
stringDefinicja
Suma do zapłaty.Jeśli w kwoty są grosze, wyślij je z separatorem „”.
Przykład: 10.28Typ parametru
stringDefinicja
Kod walutyTyp parametru
stringmin: 1max: 100alpha_dashDefinicja
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
stringDomyślna wartość
nullDefinicja
Kod sieci BlockchainTyp parametru
stringmin: 6max: 255urlDomyślna wartość
nullDefinicja
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: 255urlDomyślna wartość
nullDefinicja
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: 255urlDomyślna wartość
nullDefinicja
URL, do którego webhooks ze statusem płatności zostaną wysłaneTyp parametru
booleanDomyślna wartość
trueDefinicja
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: 43200Domyślna wartość
3600Definicja
Żywotność wydanej faktury (w sekundach)Typ parametru
stringDefinicja
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 : BTCAPI 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: 100Domyślna wartość
0Definicja
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: 5Domyślna wartość
0Definicja
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 saldoTyp parametru
stringmax: 255Domyślna wartość
nullDefinicja
Dodatkowe informacje dla Ciebie (nie pokazane klientowi)Typ parametru
arrayDomyś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. StrukturaTyp parametru
stringDomyślna wartość
nullDefinicja
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: 90Domyślna wartość
nullDefinicja
Liczby dodatnie:
pozwala ustawić zniżkę.
Aby ustawić 5% rabatu na płatność, powinieneś przekazać wartość: 5Liczby 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
booleanDomyślna wartość
falseDefinicja
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
| Nazwa | Definicja |
|---|---|
| currency* | Kod waluty |
| network | Kod sieci Blockchain |
Definicja
Kod walutyDefinicja
Kod sieci Blockchain
* - obowiązkowy parametr
Struktura except_currencies
| Nazwa | Definicja |
|---|---|
| currency* | Kod waluty |
| network | Kod sieci Blockchain |
Definicja
Kod walutyDefinicja
Kod sieci Blockchain
* - obowiązkowy parametr
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"
}'KopiaOdpowiedź
Parametry odpowiedzi
| Nazwa | Typ parametru | Definicja |
|---|---|---|
| uuid | string | Faktura uuid |
| order_id | string|null | Zamów identyfikator w twoim systemie |
| amount | string | Ilość faktury |
| payment_amount | string|null | Kwota zapłacona przez klienta |
| payment_amount_usd | string|null | Kwota faktycznie opłacona przez klienta w USD |
| payer_amount | string|null | Kwota w payer_currency , którą klient musi zapłacić, w tym zniżka lub dodatkowa prowizja. |
| payer_amount_exchange_rate | string|null | Kurs wymiany zastosowany w momencie realizacji płatności |
| discount_percent | integer|null | Procent rabatu lub dodatkowa prowizja, która została przekazana w parametrach żądania |
| discount | string | 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 |
| payer_currency | string|null | Waluta, w której klient musi dokonać płatności. |
| currency | string | Kod waluty faktury |
| comments | string|null | Komentarz |
| merchant_amount | string|null | 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. |
| network | string|null | Kod sieci Blockchain |
| address | string|null | Adres portfela do płatności |
| from | string|null | Adres portfela, z którego dokonano płatności |
| txid | string|null | Hash transakcji |
| payment_status | string | Status płatności Wszystkie statusy płatności |
| url | string | Strona płatności URL |
| expired_at | integer|null | Znacznik czasu wygaśnięcia faktury |
| status | string | Status płatności Wszystkie statusy płatności |
| is_final | boolean | Czy faktura jest sfinalizowana.Po sfinalizowaniu faktury nie można zapłacić faktury (jest ona opłacana lub wygasła) |
| additional_data | string|null | Dodatkowe informacje |
| created_at | string|null | Data utworzenia faktury. Strefa czasowa to UTC+3 |
| updated_at | string|null | Ostatnia faktura zaktualizowana data. Strefa czasowa to UTC+3 |
| commission | string|null | Kwota Komisji Cryptomus |
| address_qr_code | string|null | Kod QR adresu |
| convert | 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 | |
| convert.to_currency | string | Kod waluty, do którego płatność zostanie przekonwertowana |
| convert.commission | string | Opłata za konwersję |
| convert.rate | string|null | Współczynnik konwersji |
| convert.amount | string|null | Kwota konwersji w to_currency, która została dodana do równowagi sprzedawcy, przy odjęciu wszystkich prowizji. |
| convert_from | Informacje o walucie, z której dokonano nieprawidłowej płatnościObecny, jeśli płatność jest nieprawidłowa | |
| convert_from.from_currency | string | Z waluty |
| convert_from.from_amount | string|null | Kwota od |
| convert_from.from_network | string|null | Kod sieci Blockchain |
Typ parametru
stringDefinicja
Faktura uuidTyp parametru
string|nullDefinicja
Zamów identyfikator w twoim systemieTyp parametru
stringDefinicja
Ilość fakturyTyp parametru
string|nullDefinicja
Kwota zapłacona przez klientaTyp parametru
string|nullDefinicja
Kwota faktycznie opłacona przez klienta w USDTyp parametru
string|nullDefinicja
Kwota w payer_currency , którą klient musi zapłacić, w tym zniżka lub dodatkowa prowizja.Typ parametru
string|nullDefinicja
Kurs wymiany zastosowany w momencie realizacji płatnościTyp parametru
integer|nullDefinicja
Procent rabatu lub dodatkowa prowizja, która została przekazana w parametrach żądaniaTyp parametru
stringDefinicja
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_amountTyp parametru
string|nullDefinicja
Waluta, w której klient musi dokonać płatności.Typ parametru
stringDefinicja
Kod waluty fakturyTyp parametru
string|nullDefinicja
KomentarzTyp parametru
string|nullDefinicja
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|nullDefinicja
Kod sieci BlockchainTyp parametru
string|nullDefinicja
Adres portfela do płatnościTyp parametru
string|nullDefinicja
Adres portfela, z którego dokonano płatnościTyp parametru
string|nullDefinicja
Hash transakcjiTyp parametru
stringTyp parametru
stringDefinicja
Strona płatności URLTyp parametru
integer|nullDefinicja
Znacznik czasu wygaśnięcia fakturyTyp parametru
stringTyp parametru
booleanDefinicja
Czy faktura jest sfinalizowana.Po sfinalizowaniu faktury nie można zapłacić faktury (jest ona opłacana lub wygasła)Typ parametru
string|nullDefinicja
Dodatkowe informacjeTyp parametru
string|nullDefinicja
Data utworzenia faktury. Strefa czasowa to UTC+3Typ parametru
string|nullDefinicja
Ostatnia faktura zaktualizowana data. Strefa czasowa to UTC+3Typ parametru
string|nullDefinicja
Kwota Komisji CryptomusTyp parametru
string|nullDefinicja
Kod QR adresuDefinicja
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_codeTyp parametru
stringDefinicja
Kod waluty, do którego płatność zostanie przekonwertowanaTyp parametru
stringDefinicja
Opłata za konwersjęTyp parametru
string|nullDefinicja
Współczynnik konwersjiTyp parametru
string|nullDefinicja
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łowaTyp parametru
stringDefinicja
Z walutyTyp parametru
string|nullDefinicja
Kwota odTyp parametru
string|nullDefinicja
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}KopiaWię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}KopiaPoproś 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}KopiaPoproś 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}KopiaPoproś 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}KopiaPoproś 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}KopiaPoproś 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}KopiaMoż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}KopiaJeśli podałeś kod sieciowy, który nie jest obsługiwany
1{
2 "state": 1,
3 "message": "The network was not found"
4}KopiaJeś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}KopiaJeś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}KopiaPayments.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}KopiaJeśli przypadkowo coś się dzieje podczas konwersji na to_currency :
1{
2 "state": 1,
3 "message": "Error convert to_currency"
4}KopiaJeś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}KopiaJeś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}KopiaJeś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}KopiaJeś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}KopiaWewnętrzny błąd serwera
kod : 500
przykładowe odpowiedzi:
1{
2 "message": "Server error, #1",
3 "code": 500,
4 "error": null
5}Kopia