Skip to main content

Create Fiat Payment

POST 
/checkout/payin/fiat

Create a Hosted Checkout session to enable a customer to accept a fiat payment 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.

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

    oneOf

    Type stringrequired

    Possible values: [Individual]

    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
    Email email

    Customer's email address.

    PhoneNumber string

    Customer's phone number.

    Possible values: Value must match regular expression ^\+[0-9]{6,15}$

    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
    UnitAmount PositiveDecimal (string)required

    Amount of a single unit of the line item. Must be in the same currency as the transaction.

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

    Example: 10.1
    TotalAmount PositiveDecimal (string)required

    Total amount of the line item (UnitAmount * Quantity). Must be in the same 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​

Checkout request created

Schema

    HostedURL urirequired

    URL to redirect the customer to the checkout page.

    CheckoutSession

    object

    required

    CheckoutSessionID stringrequired

    Unique ID of session.

    PaymentMethodCategory PaymentMethodCategory (string)

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

    • Bank
    • Card
    • Identifier
    Example: Bank
    SourceCurrency AssetID (string)required

    A scalar representing a financial asset code. Suitable for use in cases where exactly one of the currency codes must be provided.

    Example: USD
    DestinationCurrency AssetID (string)required

    A scalar representing a financial asset code. Suitable for use in cases where exactly one of the currency codes must be provided.

    Example: USD
    SourceAmount PositiveDecimal (string)

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

    Example: 10.1
    DestinationAmount PositiveDecimal (string)

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

    Example: 10.1
    AuthorizedAmount PositiveDecimal (string)

    Maximum amount that can be charged for this transaction.

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

    Example: 10.1
    Status stringrequired

    Status of CheckoutSession:

    • Pending
    • Failed
    • Settled

    Note: other statuses could be added in the future

    ExternalID string

    Unique identifier in user's system.

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

    LineItems

    object[]

    required

    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
    UnitAmount PositiveDecimal (string)required

    Amount of a single unit of the line item. Must be in the same currency as the transaction.

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

    Example: 10.1
    TotalAmount PositiveDecimal (string)required

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

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

    Example: 10.1

  • ]

    • Type stringrequired

    Type of checkout session:

    • PayinCrypto
    • PayinFiat
    • PayoutFiat
    Expiry date-time

    Time the checkout expires (example: 2020-01-01T00:00:00Z)

    Created date-timerequired

    Time the checkout was created (example: 2020-01-01T00:00:00Z)

Callbacks​

POST 
/

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

Body

required

    EventType stringrequired

    Type of the event being sent:

    • Transaction
    • FiatDeposit
    • CheckoutSession
    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

    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
    • Solana/SolanaDevnet
    • 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)required

    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

    Type stringrequired

    Possible values: [FiatPaymentMethodBankDisplay]

    AccountNumber string
    BankCode string

    Breakdown

    object[]

    This list explains how the transaction amount was calculated.

  • Array [

    • Type TransactionBreakdownType (string)required

    What does the breakdown item amount refer to:

    • ChannelFee: amount withheld by the system from the fiat payment
    • BusinessFee: amount to withheld on behalf of the business over its customers transactions
    • Remaining: amount withheld by the system from the fiat payment
    Amount PositiveDecimal (string)required

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

    Example: 10.1

  • ]

    • AdjustmentFor

    object

    Identifies a transaction that this transaction adjusts and details about the adjustment.

    AdjustedTransactionID uuidrequired

    ID of the transaction being adjusted.

    AdjustmentID uuidrequired

    Identifies the adjustment. For adjustment that requires multiple transactions this will be the same for each transaction.

    Reason stringrequired

    Why the adjustment was made:

    • ExchangeRateCorrection
    UserID stringrequired

    User ID of the event.

Callbacks Responses​

Callback received successfully

Loading...