Payments API documentation

Create a new payment.

POST /api/payments/create-payment

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.

application/json

Body

usdAmount string

Payment amount in USD. Required if nanoAmount is not provided.
nanoAmount string

Payment amount in Nano (Raw). Required if usdAmount is not provided.
orderId string

Optional identifier for the transaction for merchant use. Not used by Madora.
orderDescription string

Optional description for the transaction for merchant use. Not used by Madora.
paymentCustomer object

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.
Hide paymentCustomer attributes Show paymentCustomer attributes
- firstName string Required
  
  First name
- lastName string Required
  
  Last name
- email string Required
  
  Valid email address
- organizationName string
  
  Company
- country string Required
  
  2 Character Country ISO Code (see https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
- administrativeArea string
  
  State / Province / Region (ISO code when available)
- subAdministrativeArea string
  
  County / District (unused in US addresses)
- locality string
  
  City / Town
- dependentLocality string
  
  Dependent locality (unused in US addresses)
- postalCode string
  
  Postal code / ZIP Code
- thoroughfare string
  
  Street address
- premise string
  
  Apartment, Suite, Box number, etc.
- subPremise string
  
  Sub premise (unused in US addresses)
- phoneNumber string Required
  
  Unformatted phone number, with country code when possible (numerical only, no dashes, parantheses, etc.)

Responses

• 200

200 OK
Hide response attributes Show response attributes object
- paymentIdentifier string
  
  Unique identifier for the created payment.
- usdAmount number(double)
  
  Required payment amount in USD. Will also except a string field, so long as it can be parsed into a number.
- rawNanoAmount string
  
  Required payment amount in Nano (Raw).
- friendlyNanoAmount string
  
  Required payment amount in Nano in a user-friendly format.
- paymentAddress string
  
  Nano address to be displayed to the user, which is where the payment should be sent to.
• 400

400 Bad Request
Hide response attributes Show response attributes object
- errorCode string Required
  
  Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
- errorMessage string Required
• 401

401 Unauthorized
Hide response attributes Show response attributes object
- errorCode string Required
  
  Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
- errorMessage string Required
• 500

500 Internal Server Error
Hide response attributes Show response attributes object
- errorCode string Required
  
  Values are internal, invalidAmount, badInput, transactionTooLarge, unsupportedLocation, notEnabled, paymetNotFound, wrongAccount, alreadyCancelled, authMissing, or authInvalid.
- errorMessage string Required

POST /api/payments/create-payment

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

Request example

{
  "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"
  }
}

Response examples (200)

{
  "paymentIdentifier": "f390682f-4ded-41d6-adfd-80c54e85d73f",
  "usdAmount": 2.05,
  "rawNanoAmount": "1000000000000000000000000000000",
  "friendlyNanoAmount": "1.000000",
  "paymentAddress": "nano_3g6ue89jij6bxaz3hodne1c7gzgw77xawpdz4p38siu145u3u17c46or4jeu"
}

Response examples (400)

{
  "errorCode": "internal",
  "errorMessage": "string"
}

Response examples (401)

{
  "errorCode": "internal",
  "errorMessage": "string"
}

Response examples (500)

{
  "errorCode": "internal",
  "errorMessage": "string"
}