The Madora Payments API provides an easy way to accept Nano as a payment on your website, in your online store, video game, or other environment.
This is the documentation for version 1.0.0
of the API. Last update on Jun 8, 2022.
https://madora.ioThe API accepts 3 different authentication methods:
Madora.io uses HTTP Basic Authentication to verify all requests (see: https://en.wikipedia.org/wiki/Basic_access_authentication). API Access Keys may be generated on your Madora account page, after completing client onboarding. To make a request using a given key, the key should be combined with the secret in the form: key:secret, and then Base64 encoded. The encoded value can then added to the "Authorization" header as follows: Authorization: Basic [encoded_value]
Instant Payment Notifications use a different authentication method than the rest of the API. A payment account has an IPN secret key associated with it, which can be accessed on the account page. This secret key is used to create a signature from the request, which is passed with all IPNs to verify that the source is legitimate. The signature will be passed in the header as x-madora-sig, and is created using HMAC and SHA256.
Given an amount (in USD or raw nano), returns a payment identifier (used to track the payment in the Madora system) and a nano address to serve as the destination for the payee. The response contains payment amounts, payment address, and a unique identifier created by Madora to refer to the payment later. Payments will fail if the user does not complete them within 15 minutes, and a new payment will need to be created. As part of Madora's AML policy, payments may not exceed $600. Additionally, payments are only available in supported regions.
Payment amount in USD. Required if nanoAmount is not provided.
Payment amount in Nano (Raw). Required if usdAmount is not provided.
Optional identifier for the transaction for merchant use. Not used by Madora.
Optional description for the transaction for merchant use. Not used by Madora.
KYC (Know Your Customer) information used as part of Madora's required Anti-Money Laundering practices. Address information uses the Drupal Address Field (https://www.drupal.org/project/addressfield) to allow international address inputs. This means many fields will be optional for addresses in a given country. Descriptions provided describe the usage in a United States-based address. Other countries should use best judgement, or contact support@madora.io for best practices.
First name
Last name
Valid email address
Company
2 Character Country ISO Code (see https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
State / Province / Region (ISO code when available)
County / District (unused in US addresses)
City / Town
Dependent locality (unused in US addresses)
Postal code / ZIP Code
Street address
Apartment, Suite, Box number, etc.
Sub premise (unused in US addresses)
Unformatted phone number, with country code when possible (numerical only, no dashes, parantheses, etc.)
200 OK
Unique identifier for the created payment.
Required payment amount in USD. Will also except a string field, so long as it can be parsed into a number.
Required payment amount in Nano (Raw).
Required payment amount in Nano in a user-friendly format.
Nano address to be displayed to the user, which is where the payment should be sent to.
400 Bad Request
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
401 Unauthorized
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
500 Internal Server Error
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
curl \
-X POST https://madora.io/api/payments/create-payment \
--user "username:password" \
-H "Content-Type: application/json" \
-d '{"usdAmount":"2.05","nanoAmount":"1000000000000000000000000000000","orderId":"1","orderDescription":"test transaction","paymentCustomer":{"firstName":"John","lastName":"Doe","email":"support@madora.io","organizationName":"Madora","country":"US","administrativeArea":"MA","subAdministrativeArea":"string","locality":"Boston","dependentLocality":"string","postalCode":"02133","thoroughfare":"24 Beacon St","premise":"string","subPremise":"string","phoneNumber":"+16177222000"}}'{
"usdAmount": "2.05",
"nanoAmount": "1000000000000000000000000000000",
"orderId": "1",
"orderDescription": "test transaction",
"paymentCustomer": {
"firstName": "John",
"lastName": "Doe",
"email": "support@madora.io",
"organizationName": "Madora",
"country": "US",
"administrativeArea": "MA",
"subAdministrativeArea": "string",
"locality": "Boston",
"dependentLocality": "string",
"postalCode": "02133",
"thoroughfare": "24 Beacon St",
"premise": "string",
"subPremise": "string",
"phoneNumber": "+16177222000"
}
}{
"paymentIdentifier": "f390682f-4ded-41d6-adfd-80c54e85d73f",
"usdAmount": 2.05,
"rawNanoAmount": "1000000000000000000000000000000",
"friendlyNanoAmount": "1.000000",
"paymentAddress": "nano_3g6ue89jij6bxaz3hodne1c7gzgw77xawpdz4p38siu145u3u17c46or4jeu"
}{
"errorCode": "internal",
"errorMessage": "string"
}{
"errorCode": "internal",
"errorMessage": "string"
}{
"errorCode": "internal",
"errorMessage": "string"
}Cancel a pending payment of the provided payment identifier. Will fail if the payment has already been cancelled, errored, or completed. Payments will automatically cancel if they are not completed after 15 minutes, which will mark them as errored.
Unique identifier for the created payment.
200 OK
Unique identifier for the created payment.
Unique identifier for the created payment. Successful transactions will be marked as completed. Transactions that have failed due to technical reasons will be marked Error, while transactions that were flagged and denied by our Anti-Money Laundering program will be marked as AMLError. Transactions that are flagged will always automatically return money to the user.
Values are Waiting, Cancelled, Error, AMLError, or Completed.
Simple boolean to determine if a payment has successfully completed.
Datetime of when the payment was first created, in the format: uuuu-MM-dd'T'HH:mm:ss
Optional identifier for the transaction for merchant use. Not used by Madora.
Optional description for the transaction for merchant use. Not used by Madora.
400 Bad Request
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
401 Unauthorized
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
500 Internal Server Error
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
curl \
-X POST https://madora.io/api/payments/cancel-payment \
--user "username:password" \
-H "Content-Type: application/json" \
-d '{"paymentIdentifier":"f390682f-4ded-41d6-adfd-80c54e85d73f"}'{
"paymentIdentifier": "f390682f-4ded-41d6-adfd-80c54e85d73f"
}{
"paymentIdentifier": "f390682f-4ded-41d6-adfd-80c54e85d73f",
"status": "Waiting",
"isComplete": true,
"createdDatetime": "2022-05-04T09:42:00+00:00",
"orderId": "1",
"orderDescription": "test transaction"
}{
"errorCode": "internal",
"errorMessage": "string"
}{
"errorCode": "internal",
"errorMessage": "string"
}{
"errorCode": "internal",
"errorMessage": "string"
}Returns the current status of a payment given a unique payment identifier. Even if using webhooks, we recommend using this endpoint to verify payment completion.
Unique identifier for the created payment.
200 OK
Unique identifier for the created payment.
Unique identifier for the created payment. Successful transactions will be marked as completed. Transactions that have failed due to technical reasons will be marked Error, while transactions that were flagged and denied by our Anti-Money Laundering program will be marked as AMLError. Transactions that are flagged will always automatically return money to the user.
Values are Waiting, Cancelled, Error, AMLError, or Completed.
Simple boolean to determine if a payment has successfully completed.
Datetime of when the payment was first created, in the format: uuuu-MM-dd'T'HH:mm:ss
Optional identifier for the transaction for merchant use. Not used by Madora.
Optional description for the transaction for merchant use. Not used by Madora.
400 Bad Request
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
401 Unauthorized
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
500 Internal Server Error
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
curl \
-X POST https://madora.io/api/payments/payment-status \
--user "username:password" \
-H "Content-Type: application/json" \
-d '{"paymentIdentifier":"f390682f-4ded-41d6-adfd-80c54e85d73f"}'{
"paymentIdentifier": "f390682f-4ded-41d6-adfd-80c54e85d73f"
}{
"paymentIdentifier": "f390682f-4ded-41d6-adfd-80c54e85d73f",
"status": "Waiting",
"isComplete": true,
"createdDatetime": "2022-05-04T09:42:00+00:00",
"orderId": "1",
"orderDescription": "test transaction"
}{
"errorCode": "internal",
"errorMessage": "string"
}{
"errorCode": "internal",
"errorMessage": "string"
}{
"errorCode": "internal",
"errorMessage": "string"
}Amount in Nano (Raw).
200 OK
Amount in USD.
400 Bad Request
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
401 Unauthorized
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
500 Internal Server Error
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
curl \
-X POST https://madora.io/api/payments/nano-to-usd \
--user "username:password" \
-H "Content-Type: application/json" \
-d '{"nanoAmount":"1000000000000000000000000000000"}'{
"nanoAmount": "1000000000000000000000000000000"
}{
"usdAmount": "2.05"
}{
"errorCode": "internal",
"errorMessage": "string"
}{
"errorCode": "internal",
"errorMessage": "string"
}{
"errorCode": "internal",
"errorMessage": "string"
}200 OK
Amount in Nano (Raw).
400 Bad Request
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
401 Unauthorized
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
500 Internal Server Error
Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
curl \
-X POST https://madora.io/api/payments/usd-to-nano \
--user "username:password" \
-H "Content-Type: application/json" \
-d '{"usdAmount":"2.05"}'{
"usdAmount": "2.05"
}{
"nanoAmount": "1000000000000000000000000000000"
}{
"errorCode": "internal",
"errorMessage": "string"
}{
"errorCode": "internal",
"errorMessage": "string"
}{
"errorCode": "internal",
"errorMessage": "string"
}This endpoint returns all jurisdictions that Madora is able to operate in. This endpoint is the recommended option for providing client-side logic about whether to display Madora as a payment option. As Madora expands our compliance to new states, this endpoint will provide the most up-to-date list of allowed states.
An array of supported countries, using 2 letter ISO Country codes, as defined in ISO 3166-1: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.
An array of supported states/provinces/etc, using the second part of the 2 letter ISO codes for states/provinces, as defined in ISO 3166-2: https://en.wikipedia.org/wiki/ISO_3166-2:US and https://en.wikipedia.org/wiki/ISO_3166-2:CA
curl \
-X GET https://madora.io/api/payments/supported \
--user "username:password" \
-H "apiKey: $API_KEY"{
"supportedCountries": [
"US"
],
"supportedAdministrativeAreas": [
"CA",
"MA"
]
}Instant Payment Notifications (IPNs, also known as a webhook or callback) are used to quickly notify when a payment has been completed. When a payment is completed, the webhook will send a post request to the destination url configured on the Madora Payment Account. Responses to this webhook are ignored.
Unique identifier for the created payment.
Unique identifier for the created payment. Successful transactions will be marked as completed. Transactions that have failed due to technical reasons will be marked Error, while transactions that were flagged and denied by our Anti-Money Laundering program will be marked as AMLError. Transactions that are flagged will always automatically return money to the user.
Values are Waiting, Cancelled, Error, AMLError, or Completed.
Simple boolean to determine if a payment has successfully completed.
Datetime of when the payment was first created, in the format: uuuu-MM-dd'T'HH:mm:ss
Optional identifier for the transaction for merchant use. Not used by Madora.
Optional description for the transaction for merchant use. Not used by Madora.
{
"paymentIdentifier": "f390682f-4ded-41d6-adfd-80c54e85d73f",
"status": "Waiting",
"isComplete": true,
"createdDatetime": "2022-05-04T09:42:00+00:00",
"orderId": "1",
"orderDescription": "test transaction"
}