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.

If the Customer object is provided, the customer will be upserted. If the Customer object is not provided, the CustomerID should refer to an existing customer.

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 (main/sandbox):
• BTC/BTC_TEST
• USDC/USDC_TEST
Example: BTC
FiatAmount PositiveDecimal (string)required
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)

A unique identifier used in the business system to store a reference for the transaction. This field allows businesses to track and manage transactions within their internal systems.

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

Quantity of the line item. Must be greater than zero.

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

Example: 10.1

UnitFiatAmount PositiveDecimal (string)required

Fiat amount of a single unit of the line item. Must be in the same fiat currency as the transaction.

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

Example: 10.1

TotalFiatAmount PositiveDecimal (string)required

Total fiat amount of the line item (UnitFiatAmount * Quantity). Must be in the same fiat currency as the transaction.

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

NOAH's unique identifier for the transaction.

PublicID string

The public blockchain transaction id or hash. This identifier is only available for transactions that are broadcast to a public network as well as some private networks where available, e.g. Lightning

Network Network (string)required

Payments network (main/sandbox):

• Bitcoin/BitcoinTest
• Lightning/LightningTest
• Ethereum/EthereumTestSepolia
• PolygonPos/PolygonTestAmoy
• OffNetwork/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)

A unique identifier used in the business system to store a reference for the transaction. This field allows businesses to track and manage transactions within their internal systems.

Possible values: non-empty and <= 36 characters

Amount PositiveDecimal (string)

The net crypto amount transacted, affecting the balance. This amount excludes the NetworkFee. For buy transactions, this is the amount after payment fees. For sell transactions, this is the amount before payment fees.

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

Example: 10.1

NetworkFee PositiveDecimal (string)

Amount paid to cover the the onchain network or gas fee associated with the transaction, if applicable.

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

Example: 10.1

CryptoCurrency CryptoCurrencyCode (string)required

Cryptocurrency (main/sandbox):

• BTC/BTC_TEST
• USDC/USDC_TEST

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

The final amount that has been debited (for buy transactions) or credited (for sell transactions) from the payment method.

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

Example: 10.1

FeeAmount PositiveDecimal (string)required

The fee applied to this payment.

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

Example: 10.1

Rate PositiveDecimal (string)

Crypto/Fiat exchange rate.

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

FiatDepositID string

The ID of the deposit when the payment originated from a deposit.

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.

FiatPaymentMethod

object

Information about the fiat payment method used to facilitate this transaction.

ID stringrequired

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

Country CountryCode (string)

ISO 3166-1 alpha-2 country code.

Example: US

PaymentMethodCategory PaymentMethodCategory (string)required

Categorizes one or more PaymentMethodTypes into broader groups. Useful for listing channels, displaying payment methods:

• Bank
• Card
• Identifier

Example: Bank

DisplayDetails

object

required

Contains information to display each payment method, with fields tailored to the specific type (e.g., last four digits or account number) to help identify the payment method.

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

Breakdown

object[]

Transactions can be split, or brokendown, into parts according to the needs of the user. This list explains how the transaction amount should be split.

Array [

Type TransactionBreakdownType (string)required

What does the breakdown item amount refer to:

• BusinessFee
• Remaining

Amount PositiveDecimal (string)required

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

Example: 10.1

]

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",
      "FiatDepositID": "string"
    },
    "Orchestration": {
      "RuleID": "string",
      "RuleExecutionID": "string"
    },
    "FiatPaymentMethod": {
      "ID": "string",
      "CustomerID": "550e8400-e29b-41d4-a716-446655440000",
      "Country": "US",
      "PaymentMethodCategory": "Bank",
      "DisplayDetails": {}
    },
    "Breakdown": [
      {
        "Type": "string",
        "Amount": "10.1"
      }
    ]
  }
}

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

NOAH's unique identifier for the transaction.

PublicID string

The public blockchain transaction id or hash. This identifier is only available for transactions that are broadcast to a public network as well as some private networks where available, e.g. Lightning

Network Network (string)required

Payments network (main/sandbox):

• Bitcoin/BitcoinTest
• Lightning/LightningTest
• Ethereum/EthereumTestSepolia
• PolygonPos/PolygonTestAmoy
• OffNetwork/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)

A unique identifier used in the business system to store a reference for the transaction. This field allows businesses to track and manage transactions within their internal systems.

Possible values: non-empty and <= 36 characters

Amount PositiveDecimal (string)

The net crypto amount transacted, affecting the balance. This amount excludes the NetworkFee. For buy transactions, this is the amount after payment fees. For sell transactions, this is the amount before payment fees.

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

Example: 10.1

NetworkFee PositiveDecimal (string)

Amount paid to cover the the onchain network or gas fee associated with the transaction, if applicable.

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

Example: 10.1

CryptoCurrency CryptoCurrencyCode (string)required

Cryptocurrency (main/sandbox):

• BTC/BTC_TEST
• USDC/USDC_TEST

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

The final amount that has been debited (for buy transactions) or credited (for sell transactions) from the payment method.

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

Example: 10.1

FeeAmount PositiveDecimal (string)required

The fee applied to this payment.

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

Example: 10.1

Rate PositiveDecimal (string)

Crypto/Fiat exchange rate.

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

FiatDepositID string

The ID of the deposit when the payment originated from a deposit.

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.

FiatPaymentMethod

object

Information about the fiat payment method used to facilitate this transaction.

ID stringrequired

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

Country CountryCode (string)

ISO 3166-1 alpha-2 country code.

Example: US

PaymentMethodCategory PaymentMethodCategory (string)required

Categorizes one or more PaymentMethodTypes into broader groups. Useful for listing channels, displaying payment methods:

• Bank
• Card
• Identifier

Example: Bank

DisplayDetails

object

required

Contains information to display each payment method, with fields tailored to the specific type (e.g., last four digits or account number) to help identify the payment method.

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

Breakdown

object[]

Transactions can be split, or brokendown, into parts according to the needs of the user. This list explains how the transaction amount should be split.

Array [

Type TransactionBreakdownType (string)required

What does the breakdown item amount refer to:

• BusinessFee
• Remaining

Amount PositiveDecimal (string)required

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

Example: 10.1

]

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

The amount of the deposit.

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.

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.

Status FiatDepositStatus (string)required

Status of the deposit.

Possible values: [Pending, Failed, Settled]

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

Contains information to display each payment method, with fields tailored to the specific type (e.g., last four digits or account number) to help identify the payment method.

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...