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: 128alpha_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 |
course_source | stringmin: 4max: 20Dostępne wartości• Binance• BinanceP2P• Exmo• Kucoin• Garantexio | Jeś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_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 kryptomus i otrzymasz dochód z ich obrotu. |
discount_percent | integermin: -99max: 100 | 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: 128alpha_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
stringDefinicja
Kod sieci BlockchainTyp parametru
stringmin: 6max: 255urlDefinicja
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: 255urlDefinicja
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: 255urlDefinicja
URL, do którego Webhooks ze statusem płatności zostaną wysłaneTyp parametru
booleanDefinicja
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: 43200Definicja
Ż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: 100Definicja
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: 5Definicja
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: 255Definicja
Dodatkowe informacje dla Ciebie (nie pokazane klientowi)Typ parametru
arrayDefinicja
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
arrayDefinicja
Lista wykluczonych walut do płatności StrukturaTyp parametru
stringmin: 4max: 20
Dostępne wartości- Binance- BinanceP2P- Exmo- Kucoin- GarantexioDefinicja
Usługa, z której kursy walut są pobierane w celu konwersji we fakturze.Typ parametru
stringDefinicja
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: 100Definicja
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
booleanDefinicja
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"
}'
KOPIUJOdpowiedź
Parametry odpowiedzi
Nazwa | Definicja |
---|---|
uuid | Faktura uuid |
order_id | Zamów identyfikator w twoim systemie |
amount | Ilość faktury |
payment_amount | Kwota zapłacona przez klienta |
payer_amount | Kwota w payer_currency , którą klient musi zapłacić, w tym zniżka lub dodatkowa prowizja. |
discount_percent | Procent rabatu lub dodatkowa prowizja, która została przekazana w parametrach żądania |
discount | 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 | Waluta, w której klient musi dokonać płatności. |
currency | Kod waluty faktury |
merchant_amount | 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 | Kod sieci Blockchain |
address | Adres portfela do płatności |
from | Adres portfela, z którego dokonano płatności |
txid | Hash transakcji |
payment_status | Status płatności Wszystkie statusy płatności |
url | Strona płatności URL |
expired_at | Znacznik czasu wygaśnięcia faktury |
is_final | Czy faktura jest sfinalizowana.Po sfinalizowaniu faktury nie można zapłacić faktury (jest ona opłacana lub wygasła) |
additional_data | Dodatkowe informacje |
created_at | Data utworzenia faktury. Strefa czasowa to UTC+3 |
updated_at | Ostatnia faktura zaktualizowana data. Strefa czasowa to UTC+3 |
Definicja
Faktura uuidDefinicja
Zamów identyfikator w twoim systemieDefinicja
Ilość fakturyDefinicja
Kwota zapłacona przez klientaDefinicja
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 żądaniaDefinicja
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_amountDefinicja
Waluta, w której klient musi dokonać płatności.Definicja
Kod waluty fakturyDefinicja
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 BlockchainDefinicja
Adres portfela do płatnościDefinicja
Adres portfela, z którego dokonano płatnościDefinicja
Hash transakcjiDefinicja
Status płatności Wszystkie statusy płatnościDefinicja
Strona płatności URLDefinicja
Znacznik czasu wygaśnięcia fakturyDefinicja
Czy faktura jest sfinalizowana.Po sfinalizowaniu faktury nie można zapłacić faktury (jest ona opłacana lub wygasła)Definicja
Dodatkowe informacjeDefinicja
Data utworzenia faktury. Strefa czasowa to UTC+3Definicja
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}
KOPIUJWię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}
KOPIUJPoproś 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}
KOPIUJPoproś 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}
KOPIUJPoproś 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}
KOPIUJPoproś 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}
KOPIUJPoproś 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}
KOPIUJMoż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}
KOPIUJJeśli podałeś kod sieciowy, który nie jest obsługiwany
1{
2 "state": 1,
3 "message": "The network was not found"
4}
KOPIUJJeś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}
KOPIUJJeś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}
KOPIUJPayments.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}
KOPIUJJeśli przypadkowo coś się dzieje podczas konwersji na to_currency :
1{
2 "state": 1,
3 "message": "Error convert to_currency"
4}
KOPIUJJeś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}
KOPIUJJeś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}
KOPIUJJeś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}
KOPIUJJeś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}
KOPIUJWewnętrzny błąd serwera
kod : 500
Przykładowe odpowiedzi:
1{
2 "message": "Server error, #1",
3 "code": 500,
4 "error": null
5}
KOPIUJ