Skip to main content
POST
/
api
/
v2
/
payin
Create payin
curl --request POST \
  --url https://demo.api.loopcrypto.xyz/api/v2/payin \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "merchantId": "67e55044-10b1-426f-9247-bb680e5fe0c8",
  "amount": "599",
  "amountType": "fiat",
  "billDate": 1716211200,
  "payoutDestinationId": "pd_01jqvchm80exw95r22gczzg8rp",
  "customerId": "67e55044-10b1-426f-9247-bb680e5fe0c8",
  "paymentMethodId": "89a4b012-c3d4-45e6-f789-012345678901",
  "subscriptionRefId": "sub_1234abcd",
  "invoiceRefId": "inv_1234abcd",
  "description": "Payment for Developer plan",
  "transactionHash": "0x1234567890abcdef...",
  "exchangeRate": 1
}'
{
  "payinId": "8f47c6e9-2b3a-4d5c-9f8e-1a2b3c4d5e6f",
  "merchantId": "67e55044-10b1-426f-9247-bb680e5fe0c8",
  "amount": "100.00",
  "amountType": "fiat",
  "billDate": 1716211200,
  "invoiceId": "1234567890abcdef",
  "description": "Payment for Developer plan",
  "externalInvoiceRef": "1234567890abcdef",
  "externalSubscriptionRefId": "sub_1234abcd",
  "payinType": "subscription",
  "payinStatus": "scheduled",
  "transaction": {
    "transactionId": "0xcfdfbb523c079e47e9a17ba236fa978257d4331e96ec43997e974b97522047fe",
    "transactionUrl": "https://etherscan.io/tx/0xcfdfbb523c079e47e9a17ba236fa978257d4331e96ec43997e974b97522047fe",
    "amountTransferred": "1990000",
    "exchangeRate": {
      "currency": "USD",
      "price": "10000",
      "provider": "CoinMarketCap",
      "timestamp": 1715731200
    }
  },
  "paymentMethod": {
    "networkId": 1,
    "paymentMethodId": "1234567890abcdef",
    "paymentMethodName": "My Crypto Wallet",
    "active": true,
    "customer": {
      "customerId": "1234567890abcdef",
      "customerRefId": "1234567890abcdef"
    },
    "walletAddress": "0x1234567890abcdef",
    "isDefault": true,
    "token": {
      "symbol": "USDC",
      "tokenId": "123e4567-e89b-12d3-a456-426614174000",
      "address": "0x1234567890abcdef",
      "decimals": 6,
      "exchangeRates": [
        {
          "currency": "USD",
          "price": "10000",
          "provider": "CoinMarketCap",
          "timestamp": 1715731200
        }
      ]
    },
    "preAuthorization": {
      "balance": "100",
      "authorization": "49.9"
    },
    "status": "ok"
  },
  "payoutDestination": {
    "networkId": 1,
    "walletAddress": "0x1234567890abcdef",
    "payoutDestinationId": "1234567890abcdef",
    "settlementType": "Crypto"
  },
  "dateCreated": 1716211200
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
merchantId
string
required

The identifier of the merchant that this payin will be associated with. This merchant must already exist in the system.

Example:

"67e55044-10b1-426f-9247-bb680e5fe0c8"

​
amount
string
required

The payment amount, which can be specified in two ways:

  • For fiat currency (amountType = "fiat"): Amount in cents (e.g. $49.99 = 4999 cents)
  • For tokens (amountType = "token"): Amount including decimal places (e.g. 1 USDC = 1000000 since USDC has 6 decimal places)
Example:

"599"

​
amountType
enum<string>
required

Specifies how to interpret the amount value:

  • "fiat": Amount is in fiat currency cents (e.g. 4999 = $49.99)
  • "token": Amount includes token decimal places (e.g. 1000000 = 1 USDC with 6 decimals)
Available options:
Fiat,
Token,
fiat,
token
Example:

"fiat"

​
billDate
integer
required

The date the payment should take place, represented as a Unix timestamp. To bill the payin immediately, set the value to 0

Required range: x >= 0
Example:

1716211200

​
payoutDestinationId
string

(Optional) The payout destination the funds will be sent to for this payin. If provided:

  • The payout destination must belong to the specified merchant. If not found, the system will not check the entity's payout destinations. If not provided:
  • The merchant's default payout destination will be used if it exists.
  • If the merchant has no default payout destination, the entity's default payout destination will be used.
Example:

"pd_01jqvchm80exw95r22gczzg8rp"

​
customerId
string

The ID of the customer to charge for this payin. When provided, the customer's default payment method will be used to process the payment.

Note: Either this or paymentMethodId must be provided. If both are provided, the paymentMethodId takes precedence.

Note: This is not the customerRefId from the customer object, it is the customerId

Example:

"67e55044-10b1-426f-9247-bb680e5fe0c8"

​
paymentMethodId
string

The ID of the customer's payment method to use for this payin.

Note: Either this or customerId must be provided. If both are provided, the paymentMethodId takes precedence.

Example:

"89a4b012-c3d4-45e6-f789-012345678901"

​
subscriptionRefId
string

(Optional) An external subscription reference ID used to tie this payin to a subscription in an external system.

Example:

"sub_1234abcd"

​
invoiceRefId
string

(Optional) An invoice reference ID used to tie this payin to an invoice in an external system.

Example:

"inv_1234abcd"

​
description
string

(Optional) A description or note that provides additional detail about this payin. This can be used to help identify or provide details about the payment for internal reference or customer communications.

Maximum length: 500
Example:

"Payment for Developer plan"

​
transactionHash
string

(Optional) The transaction hash from the blockchain transaction

Example:

"0x1234567890abcdef..."

​
exchangeRate
string

(Optional) The exchange rate for the token

Example:

1

Response

Ok

​
payinId
string
required

The unique identifier for the payin

Example:

"8f47c6e9-2b3a-4d5c-9f8e-1a2b3c4d5e6f"

​
merchantId
string
required

The unique identifier of the merchant this payin is associated with

Example:

"67e55044-10b1-426f-9247-bb680e5fe0c8"

​
amount
string
required

The amount to be paid, specified in either fiat or crypto based on amountType

Example:

"100.00"

​
amountType
enum<string>
required

The type of the amount, either "fiat" or "token"

Available options:
fiat,
token
Example:

"fiat"

​
billDate
number
required

The date the payment will take place, represented as a Unix timestamp

Example:

1716211200

​
invoiceId
string
required

The unique invoice identifier representing this payin transaction

Example:

"1234567890abcdef"

​
description
string | null
required

(Optional) A description or note that provides additional context about this payin. This can be used to help identify or provide details about the payment for internal reference or customer communications.

Example:

"Payment for Developer plan"

​
externalInvoiceRef
string | null
required

(Optional) The external invoice ID used to tie this payin to an invoice in an external system

Example:

"1234567890abcdef"

​
externalSubscriptionRefId
string | null
required

(Optional) The external subscription ID used to tie this payin to a subscription in an external system

Example:

"sub_1234abcd"

​
payinType
enum<string>
required

The type of the payin, either "subscription" or "invoice"

Available options:
subscription,
invoice
Example:

"subscription"

​
payinStatus
enum<string>
required

The status of the payin, can be "scheduled", "pending", "completed", or "failed"

Available options:
scheduled,
pending,
completed,
failed,
canceled,
uncollectible,
draft
Example:

"scheduled"

​
transaction
object
required

The transaction details for the payin

​
paymentMethod
object
required

The payment method used for this payin

​
payoutDestination
object
required

The payout destination used for this payin

​
dateCreated
number
required

The date the payin record was created, represented as a Unix timestamp in seconds.

Example:

1716211200

⌘I