Skip to content
GitHub

Get an Incoming Payment

GET
/incoming-payments/{id}

A client can fetch the latest state of an incoming payment to determine the amount received into the wallet address.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string

Sub-resource identifier

Header Parameters

Section titled “Header Parameters ”
Signature-Input
string

The Signature-Input field is a Dictionary structured field containing the metadata for one or more message signatures generated from components within the HTTP message. Each member describes a single message signature. The member’s key is the label that uniquely identifies the message signature within the context of the HTTP message. The member’s value is the serialization of the covered components Inner List plus all signature metadata parameters identified by the label. The following components MUST be included: - “@method” - “@target-uri” - “authorization”. When the message contains a request body, the covered components MUST also include the following: - “content-digest” The keyid parameter of the signature MUST be set to the kid value of the JWK. See ietf-httpbis-message-signatures for more details.

Signature
string

The signature generated based on the Signature-Input, using the signing algorithm specified in the “alg” field of the JWK.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Incoming Payment Found

Any of:
Incoming Payment with payment methods

An incoming payment resource with public details.

object
id
required

The URL identifying the incoming payment.

string format: uri
walletAddress
required

The URL of the wallet address this payment is being made into.

string format: uri
completed
required

Describes whether the incoming payment has completed receiving fund.

boolean
incomingAmount
amount

The maximum amount that should be paid into the wallet address under this incoming payment.

object
value
required

The value is an unsigned 64-bit integer amount, represented as a string.

string format: uint64
assetCode
required
Asset code

The assetCode is a code that indicates the underlying asset. An ISO4217 currency code should be used whenever possible. The ISO4217 representation of the US Dollar is USD.

string
assetScale
required
Asset scale

The number of decimal places that defines the scale of the smallest divisible unit for the given asset code. It determines how an integer amount is scaled to derive the actual monetary value. For example, USD has an asset scale of 2 with the smallest unit being 0.01. An integer amount of 1000 with an assetCode of USD and assetScale of 2 translates to $10.00.

integer
<= 255
receivedAmount
required
amount

The total amount that has been paid into the wallet address under this incoming payment.

object
value
required

The value is an unsigned 64-bit integer amount, represented as a string.

string format: uint64
assetCode
required
Asset code

The assetCode is a code that indicates the underlying asset. An ISO4217 currency code should be used whenever possible. The ISO4217 representation of the US Dollar is USD.

string
assetScale
required
Asset scale

The number of decimal places that defines the scale of the smallest divisible unit for the given asset code. It determines how an integer amount is scaled to derive the actual monetary value. For example, USD has an asset scale of 2 with the smallest unit being 0.01. An integer amount of 1000 with an assetCode of USD and assetScale of 2 translates to $10.00.

integer
<= 255
expiresAt

The date and time when payments under this incoming payment will no longer be accepted.

string format: date-time
metadata

Additional metadata associated with the incoming payment. (Optional)

object
key
additional properties
any
createdAt
required

The date and time when the incoming payment was created.

string format: date-time
methods
required

The list of payment methods supported by this incoming payment.

Array
0 unique items
Any of:
object
type
required
string
Allowed values: ilp
ilpAddress
required

The ILP address to use when establishing a STREAM connection.

string
<= 1023 characters /^(g|private|example|peer|self|test[1-3]?|local)([.][a-zA-Z0-9_~-]+)+$/
sharedSecret
required

The base64 url-encoded shared secret to use when establishing a STREAM connection.

string
/^[a-zA-Z0-9-_]+$/
Examples
{
  "id": "https://ilp.interledger-test.dev/incoming-payments/2f1b0150-db73-49e8-8713-628baa4a17ff",
  "walletAddress": "https://ilp.interledger-test.dev/alice/",
  "incomingAmount": {
    "value": "2500",
    "assetCode": "USD",
    "assetScale": 2
  },
  "receivedAmount": {
    "value": "1234",
    "assetCode": "USD",
    "assetScale": 2
  },
  "completed": false,
  "expiresAt": "2022-04-12T23:20:50.52Z",
  "createdAt": "2022-03-12T23:20:50.52Z",
  "metadata": {
    "description": "Thanks for the flowers!",
    "externalRef": "INV-12876"
  },
  "methods": [
    {
      "type": "ilp",
      "ilpAddress": "g.ilp.iwuyge987y.98y08y",
      "sharedSecret": "1c7eaXa4rd2fFOBl1iydvCT1tV5TbM3RW1WLCafu_JA"
    }
  ]
}

401

Section titled “401 ”

Authorization required

object
error
required
object
code
required
string
description
required
string
details

Additional details about the error.

object
key
additional properties
any
Examples
{
  "error": {
    "code": "invalid_request",
    "description": "Error description",
    "details": {
      "anyKey": "anyValue"
    }
  }
}

Headers

Section titled “Headers ”
WWW-Authenticate
string

The address of the authorization server for grant requests in the format GNAP as_uri=<URI>

403

Section titled “403 ”

Forbidden

object
error
required
object
code
required
string
description
required
string
details

Additional details about the error.

object
key
additional properties
any
Examples
{
  "error": {
    "code": "invalid_request",
    "description": "Error description",
    "details": {
      "anyKey": "anyValue"
    }
  }
}

404

Section titled “404 ”

Incoming Payment Not Found

object
error
required
object
code
required
string
description
required
string
details

Additional details about the error.

object
key
additional properties
any
Examples
{
  "error": {
    "code": "invalid_request",
    "description": "Error description",
    "details": {
      "anyKey": "anyValue"
    }
  }
}