Create Buy

POST 
/checkout/buy

Create a Hosted Checkout session to enable a customer to onramp to your platform using the NOAH Hosted Checkout page.

Request

Header Parameters

Api-Signature string

Digitally signed JWT.

application/json

Body

required

PaymentMethodCategory PaymentMethodCategory (string)required
Categorizes one or more PaymentMethodTypes into broader groups. Useful for listing channels, displaying payment methods:
• Bank
• Card
• Identifier
Example: Bank
FiatCurrency FiatCurrencyCode (string)required
Supported fiat ISO_4217 3 letter currency codes.
Example: USD
CryptoCurrency CryptoCurrencyCode (string)required
Cryptocurrency code:
• BTC
• USDC
Example: BTC
FiatAmount PositiveDecimal (string)required
Positive decimal number in string format
Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$
Example: 10.1
ReturnURL urirequired

The URL to which the user is redirected at the end of the Hosted Checkout session. We will include the CheckoutSessionID, ExternalID and Status of the session, ie ?CheckoutSessionID={CheckoutSessionID}&ExternalID={ExternalID}&Status={Status}

Possible values: >= 10 characters and <= 1000 characters

ExternalID ExternalID (string)

Unique identifier in user's system.

Possible values: non-empty and <= 36 characters

CustomerID CustomerID (string)required
A unique ID which identifies the customer in the Business' internal system and in NOAH.
Possible values: non-empty and <= 36 characters
Example: 550e8400-e29b-41d4-a716-446655440000

Customer

object

FullName

object

required

FirstName stringrequired

user's first name

Possible values: non-empty and <= 50 characters

LastName stringrequired

user's last name (family name)

Possible values: non-empty and <= 50 characters

MiddleName string

user's middle name

Possible values: non-empty and <= 50 characters

DateOfBirth daterequired

Possible values: >= 10 characters and <= 10 characters

Example: 2024-04-16

Identities

object[]

required

Array [

IssuingCountry CountryCode (string)required

ISO 3166-1 alpha-2 country code.

Example: US

IDNumber stringrequired

Possible values: non-empty and <= 36 characters

IssuedDate date

Possible values: >= 10 characters and <= 10 characters

Example: 2024-04-16

ExpiryDate date

Possible values: >= 10 characters and <= 10 characters

Example: 2024-04-16

IDType IDType (string)required

Type of identification document:

• DrivingLicense
• NationalIDCard
• Passport
• AddressProof
• ResidencePermit
• TaxID

Example: Passport

]

PrimaryResidence

object

required

Street stringrequired

Street: the primary name of an address's street.

Possible values: >= 2 characters and <= 200 characters

Street2 string

Street2: the secondary name of an address's street.

City stringrequired

City: name of an address's city or town.

Possible values: non-empty and <= 100 characters

PostCode stringrequired

PostCode: the address's postcode

Possible values: non-empty and <= 20 characters

State stringrequired

State: the address's state / province / county. For USA and Canada, state code in ISO 3166-2 code (e.g. CA) is required.

Possible values: non-empty and <= 100 characters

Country CountryCode (string)required

ISO 3166-1 alpha-2 country code.

Example: US

LineItems

object[]

required

List of line items that your customer is purchasing using this Hosted Checkout Session. This is used for display purposes for the customer during Checkout as well as remediation of disputed payments. We do not make any calculations using this data.

Possible values: >= 1, <= 120

Array [

Description stringrequired

Description of the line item.

Possible values: non-empty and <= 140 characters

Quantity PositiveDecimal (string)required

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

UnitFiatAmount PositiveDecimal (string)required

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

TotalFiatAmount PositiveDecimal (string)required

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

]

Nonce Nonce (string)required
A string which must be unique each time a new transaction is created, like a UUID or operation sequence number. Request can be idempotently retried by using the same Nonce.
Possible values: non-empty and <= 36 characters
Example: dc879b38-494b-4de7-98a9-068703144328

Responses

200

Checkout request created

application/json

Schema

Schema

HostedURL urirequired

Hosted URL to redirect the user to fulfil the payment.

Transaction

object

required

ID uuidrequired

PublicID string

Network Network (string)required

Payments network:

• Bitcoin
• Lightning
• Ethereum
• PolygonPos
• OffNetwork

Example: Bitcoin

Created date-timerequired

When was this transaction created

Example: 2024-04-16T08:00:55Z

Status TransactionStatus (string)required

Statuses for transactions.

Possible values: [Pending, Failed, Settled]

Example: Settled

Direction TransactionDirection (string)required

Whether the transactions was a credit (in) or a debit (out) in your account

Possible values: [In, Out]

Example: In

CustomerID CustomerID (string)

A unique ID which identifies the customer in the Business' internal system and in NOAH.

Possible values: non-empty and <= 36 characters

Example: 550e8400-e29b-41d4-a716-446655440000

ExternalID ExternalID (string)

Unique identifier in user's system.

Possible values: non-empty and <= 36 characters

Amount PositiveDecimal (string)

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

NetworkFee PositiveDecimal (string)

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

CryptoCurrency CryptoCurrencyCode (string)required

Cryptocurrency code:

• BTC
• USDC

Example: BTC

FiatPayment

object

• For buy transactions, Transaction.Amount = (FiatPayment.Amount - FiatPayment.FeeAmount) / FiatPayment.Rate

• For sell transactions, Transaction.Amount = (FiatPayment.Amount + FiatPayment.FeeAmount) / FiatPayment.Rate

Amount PositiveDecimal (string)required

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

FeeAmount PositiveDecimal (string)required

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

Rate PositiveDecimal (string)

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

FiatCurrency FiatCurrencyCode (string)required

Supported fiat ISO_4217 3 letter currency codes.

Example: USD

Orchestration

object

Orchestration details for the transaction.

RuleID stringrequired

Unique identifier for the rule that is matched for the transaction.

RuleExecutionID stringrequired

Unique identifier for the execution of the rules that is matched for the transaction.

Example (from schema)

{
  "HostedURL": "string",
  "Transaction": {
    "ID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "PublicID": "string",
    "Network": "Bitcoin",
    "Created": "2024-04-16T08:00:55Z",
    "Status": "Settled",
    "Direction": "In",
    "CustomerID": "550e8400-e29b-41d4-a716-446655440000",
    "ExternalID": "string",
    "Amount": "10.1",
    "NetworkFee": "10.1",
    "CryptoCurrency": "BTC",
    "FiatPayment": {
      "Amount": "10.1",
      "FeeAmount": "10.1",
      "Rate": "10.1",
      "FiatCurrency": "USD"
    },
    "Orchestration": {
      "RuleID": "string",
      "RuleExecutionID": "string"
    }
  }
}

400

Bad request

application/json

Schema

Schema

Type ErrorType (string)
Type of error:
• InvalidMessage
• Unexpected
• ResourceNotFound
• Unauthorized
• Forbidden
• InsufficientBalance
Example: InvalidMessage
Instance string

A unique reference that identifies the specific occurrence of the problem

Action string

Action taking place which resulted in error.

Detail string

Details about the error.

Extensions

object

Additional information about the error.

Request object

Details about invalid request properties.

Features

object

Details about the disabled feature flags

property name*

string[]

List of reasons

Array [

string

]

Example (from schema)

{
  "Type": "InvalidMessage",
  "Instance": "string",
  "Action": "string",
  "Detail": "string",
  "Extensions": {
    "Request": {},
    "Features": {}
  }
}

401

Client is not authorized to perform this action

application/json

Schema

Schema

Type ErrorType (string)
Type of error:
• InvalidMessage
• Unexpected
• ResourceNotFound
• Unauthorized
• Forbidden
• InsufficientBalance
Example: InvalidMessage
Instance string

A unique reference that identifies the specific occurrence of the problem

Action string

Action taking place which resulted in error.

Detail string

Details about the error.

Extensions

object

Additional information about the error.

Request object

Details about invalid request properties.

Features

object

Details about the disabled feature flags

property name*

string[]

List of reasons

Array [

string

]

Example (from schema)

{
  "Type": "InvalidMessage",
  "Instance": "string",
  "Action": "string",
  "Detail": "string",
  "Extensions": {
    "Request": {},
    "Features": {}
  }
}

500

Internal server error

application/json

Schema

Schema

Type ErrorType (string)
Type of error:
• InvalidMessage
• Unexpected
• ResourceNotFound
• Unauthorized
• Forbidden
• InsufficientBalance
Example: InvalidMessage
Instance string

A unique reference that identifies the specific occurrence of the problem

Action string

Action taking place which resulted in error.

Detail string

Details about the error.

Extensions

object

Additional information about the error.

Request object

Details about invalid request properties.

Features

object

Details about the disabled feature flags

property name*

string[]

List of reasons

Array [

string

]

Example (from schema)

{
  "Type": "InvalidMessage",
  "Instance": "string",
  "Action": "string",
  "Detail": "string",
  "Extensions": {
    "Request": {},
    "Features": {}
  }
}

Callbacks

POST Status Update

POST 
/

Send a callback to the specified URL when the payment status updates.

application/json

Body

required

EventType stringrequired
Type of the event being sent:
• Transaction
• FiatDeposit
EventVersion integerrequired
Version of the event
Example: 0
Occurred date-timerequired
Time the event occurred
Example: 2024-04-16T08:00:55Z

Data

object

required

Data specific to the event.

oneOf

Transaction

ID uuidrequired

PublicID string

Network Network (string)required

Payments network:

• Bitcoin
• Lightning
• Ethereum
• PolygonPos
• OffNetwork

Example: Bitcoin

Created date-timerequired

When was this transaction created

Example: 2024-04-16T08:00:55Z

Status TransactionStatus (string)required

Statuses for transactions.

Possible values: [Pending, Failed, Settled]

Example: Settled

Direction TransactionDirection (string)required

Whether the transactions was a credit (in) or a debit (out) in your account

Possible values: [In, Out]

Example: In

CustomerID CustomerID (string)

A unique ID which identifies the customer in the Business' internal system and in NOAH.

Possible values: non-empty and <= 36 characters

Example: 550e8400-e29b-41d4-a716-446655440000

ExternalID ExternalID (string)

Unique identifier in user's system.

Possible values: non-empty and <= 36 characters

Amount PositiveDecimal (string)

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

NetworkFee PositiveDecimal (string)

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

CryptoCurrency CryptoCurrencyCode (string)required

Cryptocurrency code:

• BTC
• USDC

Example: BTC

FiatPayment

object

• For buy transactions, Transaction.Amount = (FiatPayment.Amount - FiatPayment.FeeAmount) / FiatPayment.Rate

• For sell transactions, Transaction.Amount = (FiatPayment.Amount + FiatPayment.FeeAmount) / FiatPayment.Rate

Amount PositiveDecimal (string)required

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

FeeAmount PositiveDecimal (string)required

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

Rate PositiveDecimal (string)

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

FiatCurrency FiatCurrencyCode (string)required

Supported fiat ISO_4217 3 letter currency codes.

Example: USD

Orchestration

object

Orchestration details for the transaction.

RuleID stringrequired

Unique identifier for the rule that is matched for the transaction.

RuleExecutionID stringrequired

Unique identifier for the execution of the rules that is matched for the transaction.

FiatDeposit

Details of a fiat deposit received by Noah.

ID stringrequired

Unique identifier of the fiat deposit.

Created date-timerequired

When was this fiat deposit created.

Example: 2024-04-16T08:00:55Z

FiatAmount PositiveDecimal (string)required

Positive decimal number in string format

Possible values: non-empty and <= 38 characters, Value must match regular expression ^[+]?([.]\d+|\d+[.]?\d*)$

Example: 10.1

FiatCurrency FiatCurrencyCode (string)required

Supported fiat ISO_4217 3 letter currency codes.

Example: USD

Reference string

Reference of the deposit.

Status FiatDepositStatus (string)required

Status of the deposit.

Possible values: [Pending, Failed, Settled, Reversed]

Example: Settled

CustomerID CustomerID (string)

A unique ID which identifies the customer in the Business' internal system and in NOAH.

Possible values: non-empty and <= 36 characters

Example: 550e8400-e29b-41d4-a716-446655440000

PaymentMethodID FiatPaymentMethodID (string)required

Existing payment method id to be used.

Possible values: non-empty and <= 150 characters

PaymentMethodType PaymentMethodType (string)required

Specific type of payment method:

• BankSepa
• BankLocal
• BankFedwire
• TokenizedCard
• IdentifierPix

Example: BankLocal

Sender

object

required

Sender's fiat payment method.

FullName string

Details

object

required

oneOf

FiatPaymentMethodBankDisplay

Type stringrequired

Possible values: [FiatPaymentMethodBankDisplay]

AccountNumber stringrequired

FiatPaymentMethodCardDisplay

Type stringrequired

Possible values: [FiatPaymentMethodCardDisplay]

Last4 stringrequired

Scheme FiatPaymentCardScheme (string)required

The card scheme:

• Mastercard
• Visa

Example: Visa

FiatPaymentMethodIdentifierDisplay

Type stringrequired

Possible values: [FiatPaymentMethodIdentifierDisplay]

IdentifierType PaymentMethodIdentifierType (string)required

Identifier type:

• PhoneNumber
• Email
• TaxID

Example: PhoneNumber

Identifier stringrequired
UserID stringrequired

User ID of the event.

Callbacks Responses

200

Callback received successfully

Loading...