/
Create a setup payment in...

Create a setup payment instrument transaction

Request

Creates a setup payment instrument transaction.

This operation makes the payment instrument available for further payments. Treat the response as a regular transaction. For example, approval links must be followed until the transaction is completed.

Security
CustomerJWT
Path
idstring, <= 50 characters^[@~\-\.\w]+$required

ID of the resource.

Bodyapplication/jsonrequired

Setup transaction resource.

websiteIdstring, <= 50 characters(WebsiteId)required

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

Example:"web_0YV7DE4Z26DQSA1AC92FBJ7SEG"
currencystring, = 3 characters(CurrencyCode)required

Currency code in ISO 4217 format.

Example:"USD"
amountnumber, (double)

Amount of the transaction.

Default:0
Example:97.97
billingAddressContactObject (object) or null
One of:

Contact's information.

redirectUrlstring or null, (uri), <= 2083 characters

URL to redirect the end-user when an offsite transaction is completed. This field defaults to the configured website URL. You may use {id} or {result} as placeholders in the URL. These placeholders are replaced with the transaction ID and result. For more information, see Placeholders.

riskMetadataobject(Risk metadata)

Risk metadata used for 3D Secure and risk scoring.

curl -i -X POST \
  'https://www.rebilly.com/_mock/catalog/all/storefront/payment-instruments/{id}/setup' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "websiteId": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
    "currency": "USD",
    "amount": 97.97,
    "billingAddress": {
      "firstName": "Benjamin",
      "lastName": "Franklin",
      "organization": "Rebilly",
      "address": "36 Craven St",
      "address2": "string",
      "city": "Austin",
      "region": "Texas",
      "country": "GB",
      "postalCode": "WC2N 5NF",
      "phoneNumbers": [
        {
          "label": "main",
          "value": "1-512-777-0269",
          "primary": true
        }
      ],
      "emails": [
        {
          "label": "main",
          "value": "rebilly@example.com",
          "primary": true
        }
      ],
      "dob": "1980-04-01",
      "jobTitle": "CEO"
    },
    "redirectUrl": "http://example.com",
    "riskMetadata": {
      "ipAddress": "93.92.91.90",
      "fingerprint": "pIUt3xbgX3l9g3YDiLbx",
      "httpHeaders": {
        "Content-Type": "application/json",
        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
      },
      "browserData": {
        "colorDepth": 24,
        "isJavaEnabled": true,
        "language": "en-US",
        "screenWidth": 1920,
        "screenHeight": 1080,
        "timeZoneOffset": 300,
        "isAdBlockEnabled": true
      },
      "extraData": {
        "kountFraudSessionId": "abcdefg12345abababab123456789012",
        "payPalMerchantSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowa",
        "threatMetrixSessionId": "dd65ratxc5qv15iph3vyoq7l6davuowadd65ratxc5qv15iph3vyoq7l6davuowa"
      }
    }
  }'

Responses

Setup transaction created.

Headers
Locationstring, (uri)

Location of the related resource.

Example:"https://api.rebilly.com/example"
X-RateLimit-Limitinteger

Total number of rate limit tokens for this request within a rate limit period. For more information, see Rate limits.

Example:3600
X-RateLimit-Remaininginteger

Remaining number of rate limit tokens for this request within the rate limit period. For example, in the sandbox environment, rate limits for non-GET endpoints are set at 3000 requests per 10 minutes.

Example:3600
Bodyapplication/json
idstring, <= 50 characters(TransactionId)read-only

ID of the transaction.

Example:"txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0"
websiteIdstring, <= 50 characters(WebsiteId)read-only

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

Example:"web_0YV7DE4Z26DQSA1AC92FBJ7SEG"
typestringread-only

Type of transaction.

Enum:"3ds-authentication""authorize""capture""credit""refund""sale""setup""void"
statusstringread-only

Status of the transaction.

Enum:"completed""conn-error""disputed""never-sent""offsite""partially-refunded""pending""refunded""sending""timeout"
resultstringread-only

Result of the transaction.

Enum:"abandoned""approved""canceled""declined""unknown"
amountnumber, (double)read-only

Total amount of the transaction.

currencystring, = 3 characters(CurrencyCode)read-only

Currency code in ISO 4217 format.

Example:"USD"
purchaseAmountnumber, (double)read-only

Amount by which the purchase is completed. If an adjustment occurs, the purchased amount may differ from the requested amount.

purchaseCurrencystring, = 3 characters(CurrencyCode)read-only

Currency code in ISO 4217 format.

Example:"USD"
requestAmountnumber, (double)read-only

Amount of the payment request. If an adjustment occurs, the purchase amount may differ from the billing amount.

requestCurrencystring, = 3 characters(CurrencyCode)read-only

Currency code in ISO 4217 format.

Example:"USD"
parentTransactionIdstring, <= 50 characters(TransactionId)

ID of the parent transaction.

Example:"txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0"
childTransactionsArray of stringsread-only

IDs of child transactions.

invoiceIdsArray of stringsread-only

Related invoice IDs.

orderIdsArray of stringsread-only

Subscription IDs of invoices that are related to the transaction.

planIdsArray of stringsread-only

Plan IDs of orders that are related to the transaction.

isRebillbooleanread-only

Specifies if the transaction is one of a number of recurring payments in a subscription, excluding trials or setup fees.

rebillNumberintegerread-only

Rebill number of the transaction. A rebill number is the number of recurring payments in a subscription, excluding trials or setup fees.

billingAddressobject(ContactObject)

Billing address.

redirectUrlstring or null, (uri), <= 2083 characters

URL where the end-user is redirected to when an offsite transaction is completed. The default value is the website URL.

retryNumberintegerread-only

Position of the transaction in the sequence of retries.

isRetrybooleanread-only

Specifies if a transaction is a retry.

billingDescriptorstring or nullread-only

Billing descriptor that appears on the periodic billing statement. For a credit card statement, this field commonly contains 12 or fewer characters.

descriptionstring, <= 255 characters

Description of the payment.

requestIdstring

Request ID of the transaction. This ID must be unique within a 24 hour period. Use this field to prevent duplicated transactions.

hasAmountAdjustmentbooleanread-only

Specifies if the transaction has amount adjustment.

gatewayNamestring or null(GatewayName)read-only

Name of the payment gateway that processed, or is selected to process, the transaction. This value is only available after a gateway is selected for the transaction.

Enum:"A1Gateway""ACI""Adyen""Aera""Aircash""Airpay""Airwallex""AsiaPay""AmazonPay""AmexVPC"
gatewayobjectread-only

Related gateway information.

customFieldsobject(ResourceCustomFields)

Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see Custom fields.

Default:{}
Example:
{
  "foo": "bar"
}
processedTimestring, (date-time)(ServerTimestamp)read-only

Date and time when the transaction is processed.

createdTimestring, (date-time)(CreatedTime)read-only

Date and time when the resource is created. This value is set automatically when the resource is created.

updatedTimestring, (date-time)(UpdatedTime)read-only

Date and time when the resource is updated. This value is set automatically when the resource is updated.

paymentInstrumentobject

Default payment instrument information.

approvalUrlstring, (uri)

URL to redirect the end-customer when transaction status is waiting-approval or offsite.

hasDccbooleanread-only

Specifies if Dynamic Currency Conversion (DCC) applies to the transaction.

dccobject or nullread-only

Details of the Dynamic Currency Conversion (DCC). If DCC is not applied to the transaction, this value is null.

tokenstringread-only

Session token used for authentication. This token provides access to created orders, invoices, and transactions.

depositRequestIdstring or null, <= 50 charactersread-only

ID of the deposit request if applicable. The created transaction is based on the properties of this deposit request.

Example:"dep_req_0YVJ65BSGYC3EAT58SEX8KY6J7"
Response
{
  "id": "txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0",
  "websiteId": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
  "type": "3ds-authentication",
  "status": "completed",
  "result": "abandoned",
  "amount": 0.1,
  "currency": "USD",
  "purchaseAmount": 0.1,
  "purchaseCurrency": "USD",
  "requestAmount": 0.1,
  "requestCurrency": "USD",
  "parentTransactionId": "txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0",
  "childTransactions": [
    "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
  ],
  "invoiceIds": [
    "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
  ],
  "orderIds": [
    "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
  ],
  "planIds": [
    "4f6cf35x-2c4y-483z-a0a9-158621f77a21"
  ],
  "isRebill": true,
  "rebillNumber": 0,
  "billingAddress": {
    "firstName": "Benjamin",
    "lastName": "Franklin",
    "organization": "Rebilly",
    "address": "36 Craven St",
    "address2": "string",
    "city": "Austin",
    "region": "Texas",
    "country": "GB",
    "postalCode": "WC2N 5NF",
    "phoneNumbers": [ … ],
    "emails": [ … ],
    "dob": "1980-04-01",
    "jobTitle": "CEO",
    "hash": "056ae6d97c788b9e98b049ebafd7b229bf852221"
  },
  "redirectUrl": "http://example.com",
  "retryNumber": 0,
  "isRetry": true,
  "billingDescriptor": "string",
  "description": "string",
  "requestId": "string",
  "hasAmountAdjustment": true,
  "gatewayName": "A1Gateway",
  "gateway": {
    "response": { … },
    "avsResponse": { … },
    "cvvResponse": { … }
  },
  "customFields": {
    "foo": "bar"
  },
  "processedTime": "2019-08-24T14:15:22Z",
  "createdTime": "2019-08-24T14:15:22Z",
  "updatedTime": "2019-08-24T14:15:22Z",
  "paymentInstrument": {
    "method": "payment-card",
    "paymentInstrumentId": "inst_0YVB8KPKNXCBR9EDX7JHSED75N"
  },
  "approvalUrl": "http://example.com",
  "hasDcc": true,
  "dcc": {
    "base": { … },
    "quote": { … },
    "outcome": "unprocessed",
    "rate": 1.25,
    "isForceDcc": true
  },
  "token": "string",
  "depositRequestId": "dep_req_0YVJ65BSGYC3EAT58SEX8KY6J7",
  "_links": [
    { … }
  ]
}