Create a new payment.

POST /api/payments/create-payment
Basic auth

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.

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 object
    • 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"
  }
}
Request examples 
{
  "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 (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 (400) 
{
  "errorCode": "internal",
  "errorMessage": "string"
}
Response examples (401) 
{
  "errorCode": "internal",
  "errorMessage": "string"
}
Response examples (401) 
{
  "errorCode": "internal",
  "errorMessage": "string"
}
Response examples (500) 
{
  "errorCode": "internal",
  "errorMessage": "string"
}
Response examples (500) 
{
  "errorCode": "internal",
  "errorMessage": "string"
}