Grant Request

POST

/

Make a new grant request

Request Body

object

access_token

required

object

access

required

A description of the rights associated with this access token.

Array

<= 3 items unique items

One of:

access-incoming

object

type

required

The type of resource request as a string. This field defines which other fields are allowed in the request object.

string

Allowed values: incoming-payment

actions

required

The types of actions the client instance will take at the RS as an array of strings.

Array<string>

unique items

Allowed values: create complete read read-all list list-all

identifier

A string identifier indicating a specific resource at the RS.

string format: uri

access-outgoing

object

type

required

The type of resource request as a string. This field defines which other fields are allowed in the request object.

string

Allowed values: outgoing-payment

actions

required

The types of actions the client instance will take at the RS as an array of strings.

Array<string>

unique items

Allowed values: create read read-all list list-all

identifier

required

A string identifier indicating a specific resource at the RS.

string format: uri

limits

Any of:

limits-outgoing

limits-outgoing

Open Payments specific property that defines the limits under which outgoing payments can be created.

object

receiver

The URL of the incoming payment that is being paid.

string format: uri

/^(https|http)://(.+)/incoming-payments/(.+)$/

debitAmount

required

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

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

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

receiveAmount

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

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

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

interval

ISO8601 repeating interval

string

limits-outgoing

Open Payments specific property that defines the limits under which outgoing payments can be created.

object

receiver

The URL of the incoming payment that is being paid.

string format: uri

/^(https|http)://(.+)/incoming-payments/(.+)$/

debitAmount

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

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

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

receiveAmount

required

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

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

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

interval

ISO8601 repeating interval

string

access-quote

object

type

required

The type of resource request as a string. This field defines which other fields are allowed in the request object.

string

Allowed values: quote

actions

required

The types of actions the client instance will take at the RS as an array of strings.

Array<string>

unique items

Allowed values: create read read-all

client

required

Wallet address of the client instance that is making this request.

When sending a non-continuation request to the AS, the client instance MUST identify itself by including the client field of the request and by signing the request.

A JSON Web Key Set document, including the public key that the client instance will use to protect this request and any continuation requests at the AS and any user-facing information about the client instance used in interactions, MUST be available at the wallet address + /jwks.json url.

If sending a grant initiation request that requires RO interaction, the wallet address MUST serve necessary client display information.

string

interact

The client instance declares the parameters for interaction methods that it can support using the interact field.

object

start

required

Indicates how the client instance can start an interaction.

Array<string>

Allowed values: redirect

finish

Indicates how the client instance can receive an indication that interaction has finished at the AS.

object

method

required

The callback method that the AS will use to contact the client instance.

string

Allowed values: redirect

uri

required

Indicates the URI that the AS will either send the RO to after interaction or send an HTTP POST request.

string format: uri

nonce

required

Unique value to be used in the calculation of the “hash” query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.

string

Examples

{
  "access_token": {
    "access": [
      {
        "type": "outgoing-payment",
        "actions": [
          "create",
          "read"
        ],
        "identifier": "https://ilp.rafiki.money/alice",
        "limits": {
          "receiver": "https://ilp.rafiki.money/incoming-payments/45a0d0ee-26dc-4c66-89e0-01fbf93156f7",
          "interval": "R12/2019-08-24T14:15:22Z/P1M",
          "debitAmount": {
            "value": "500",
            "assetCode": "USD",
            "assetScale": 2
          }
        }
      }
    ]
  },
  "client": "https://webmonize.com/.well-known/pay",
  "interact": {
    "start": [
      "redirect"
    ],
    "finish": {
      "method": "redirect",
      "uri": "https://webmonize.com/return/876FGRD8VC",
      "nonce": "4edb2194-dbdf-46bb-9397-d5fd57b7c8a7"
    }
  }
}

{
  "access_token": {
    "access": [
      {
        "type": "incoming-payment",
        "actions": [
          "create",
          "read"
        ],
        "identifier": "http://ilp.rafiki.money/bob"
      }
    ]
  },
  "client": "https://webmonize.com/.well-known/pay"
}

Responses

200

OK

One of:

object

object

interact

required

object

redirect

required

The URI to direct the end user to.

string format: uri

finish

required

Unique key to secure the callback.

string

continue

required

If the AS determines that the request can be continued with additional requests, it responds with the continue field.

object

access_token

required

A unique access token for continuing the request, called the “continuation access token”.

object

value

required

string

uri

required

The URI at which the client instance can make continuation requests.

string format: uri

wait

The amount of time in integer seconds the client instance MUST wait after receiving this request continuation response and calling the continuation URI.

integer

object

object

access_token

required

A single access token or set of access tokens that the client instance can use to call the RS on behalf of the RO.

object

value

required

The value of the access token as a string. The value is opaque to the client instance. The value SHOULD be limited to ASCII characters to facilitate transmission over HTTP headers within other protocols without requiring additional encoding.

string

manage

required

The management URI for this access token. This URI MUST NOT include the access token value and SHOULD be different for each access token issued in a request.

string format: uri

expires_in

The number of seconds in which the access will expire. The client instance MUST NOT use the access token past this time. An RS MUST NOT accept an access token past this time.

integer

access

required

A description of the rights associated with this access token.

Array

<= 3 items unique items

One of:

access-incoming

object

type

required

The type of resource request as a string. This field defines which other fields are allowed in the request object.

string

Allowed values: incoming-payment

actions

required

The types of actions the client instance will take at the RS as an array of strings.

Array<string>

unique items

Allowed values: create complete read read-all list list-all

identifier

A string identifier indicating a specific resource at the RS.

string format: uri

access-outgoing

object

type

required

The type of resource request as a string. This field defines which other fields are allowed in the request object.

string

Allowed values: outgoing-payment

actions

required

The types of actions the client instance will take at the RS as an array of strings.

Array<string>

unique items

Allowed values: create read read-all list list-all

identifier

required

A string identifier indicating a specific resource at the RS.

string format: uri

limits

Any of:

limits-outgoing

limits-outgoing

Open Payments specific property that defines the limits under which outgoing payments can be created.

object

receiver

The URL of the incoming payment that is being paid.

string format: uri

/^(https|http)://(.+)/incoming-payments/(.+)$/

debitAmount

required

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

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

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

receiveAmount

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

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

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

interval

ISO8601 repeating interval

string

limits-outgoing

Open Payments specific property that defines the limits under which outgoing payments can be created.

object

receiver

The URL of the incoming payment that is being paid.

string format: uri

/^(https|http)://(.+)/incoming-payments/(.+)$/

debitAmount

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

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

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

receiveAmount

required

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

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

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

interval

ISO8601 repeating interval

string

access-quote

object

type

required

The type of resource request as a string. This field defines which other fields are allowed in the request object.

string

Allowed values: quote

actions

required

The types of actions the client instance will take at the RS as an array of strings.

Array<string>

unique items

Allowed values: create read read-all

continue

required

If the AS determines that the request can be continued with additional requests, it responds with the continue field.

object

access_token

required

A unique access token for continuing the request, called the “continuation access token”.

object

value

required

string

uri

required

The URI at which the client instance can make continuation requests.

string format: uri

wait

The amount of time in integer seconds the client instance MUST wait after receiving this request continuation response and calling the continuation URI.

integer

Examples

{
  "interact": {
    "redirect": "https://auth.rafiki.money/4CF492MLVMSW9MKMXKHQ",
    "finish": "4105340a-05eb-4290-8739-f9e2b463bfa7"
  },
  "continue": {
    "access_token": {
      "value": "33OMUKMKSKU80UPRY5NM"
    },
    "uri": "https://auth.rafiki.money/continue/4CF492MLVMSW9MKMXKHQ",
    "wait": 30
  }
}

{
  "access_token": {
    "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
    "manage": "https://auth.rafiki.money/token/dd17a202-9982-4ed9-ae31-564947fb6379",
    "expires_in": 3600,
    "access": [
      {
        "type": "incoming-payment",
        "actions": [
          "create",
          "read"
        ],
        "identifier": "https://ilp.rafiki.money/bob"
      }
    ]
  },
  "continue": {
    "access_token": {
      "value": "33OMUKMKSKU80UPRY5NM"
    },
    "uri": "https://auth.rafiki.money/continue/4CF492MLVMSW9MKMXKHQ"
  }
}

400

Bad Request

401

Unauthorized

500

Internal Server Error