DOCOMO Digital Payment API (1.0.5)

Download OpenAPI specification:Download

Introduction

The DOCOMO Digital Payment API offers one single gateway to process a variety of traditional and alternative eCommerce payment methods.

Authentication

ApiKeyAuth

Authorization key

Security scheme type: API Key
header parameter name: X-API-Key

SignRequest

Request signature hash

Security scheme type: API Key
header parameter name: X-Signature

Quickstart



Quickstart

This API specification describes the full set of functionalities and attributes available. Please refer to our Quickstart section for detailed integration guidelines.

Checkout API

Provides API to initialize checkout process

Prepare the checkout session

Prepare the secure user session with information necessary to process payment including payment type, amount and description. As a result present operation will provide a {id} value to be used and {actionUrl} to be used to proceed with a checkout session

Authorizations:
Request Body schema: application/json
type
required
string (PaymentType)
Enum:"debit" "refund" "mandate" "preauth" "capture"
merchantTransactionId
string

Transaction Id set by merchant. Must be unique for this merchant

description
string

Description a user should see in their billing statement or payment processor payment page, or similar (if supported)

product
object (Product)

Information about the product or service paid for

payer
object (Payer)

Customer related information

paymentAccount
object (PaymentAccount)

Payment method with related account information

amount
object (Amount)
returnUrl
string

URL to redirect the user once payment has been successfully completed. Required only for payment methods requiring redirection.

cancelUrl
string

URL to redirect the user once payment has been successfully completed. Required only for payment methods requiring redirection.

Responses

200

OK

post /v1/sessions
/v1/sessions

Request samples

application/json
Copy
Expand all Collapse all
{
  • "type": "debit",
  • "merchantTransactionId": "string",
  • "description": "string",
  • "product":
    {
    },
  • "payer":
    {
    },
  • "paymentAccount":
    {
    },
  • "amount":
    {
    },
  • "returnUrl": "string",
  • "cancelUrl": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{}

Payment API

Provides payment capabilities

Retrieve payment transactions

Retrieve payment transactions

Authorizations:
query Parameters
limit
integer

max number of items to be returned from the collection (defaults to 10)

offset
integer

number of list items to be skipped from the collection (defaults to 0)

status
string (PaymentStatus)
Enum:"pending" "succeeded" "failed" "expired" "rejected"

resource status

type
string (PaymentType)
Enum:"debit" "refund" "mandate" "preauth" "capture"

payment type

sort
string
Enum:"createTimeAsc" "createTimeDesc" "updateTimeAsc" "updateTimeDesc"
updateTimeMax
string <date-time>
updateTimeMin
string <date-time>
createTimeMin
string <date-time>
createTimeMax
string <date-time>
subscriptionId
integer
header Parameters
X-Idempotency-Key
string <uuid>

Request identifier to ensure idempotency support

Responses

200

OK

get /v1/payments
/v1/payments

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Create a new payment transaction

Create a new payment transaction.

Authorizations:
header Parameters
X-Idempotency-Key
string <uuid>

Request identifier to ensure idempotency support

Request Body schema: application/json
One of
  • PaymentRequest
type
required
string (PaymentType)
Enum:"debit" "refund" "mandate" "preauth" "capture"
merchantTransactionId
string

Transaction Id set by merchant. Must be unique for this merchant

description
string

Description a user should see in their billing statement or payment processor payment page, or similar (if supported)

product
object (Product)

Information about the product or service paid for

payer
object (Payer)

Customer related information

paymentAccount
object (PaymentAccount)

Payment method with related account information

amount
object (Amount)
returnUrl
string

URL to redirect the user once payment has been successfully completed. Required only for payment methods requiring redirection.

cancelUrl
string

URL to redirect the user once payment has been successfully completed. Required only for payment methods requiring redirection.

Responses

200

OK

post /v1/payments
/v1/payments

Request samples

application/json
Copy
Expand all Collapse all
{
  • "type": "debit",
  • "merchantTransactionId": "string",
  • "description": "string",
  • "product":
    {
    },
  • "payer":
    {
    },
  • "paymentAccount":
    {
    },
  • "amount":
    {
    },
  • "returnUrl": "string",
  • "cancelUrl": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "status": "pending",
  • "type": "debit",
  • "merchantTransactionId": "string",
  • "description": "string",
  • "subscriptionId": "string",
  • "product":
    {
    },
  • "payer":
    {
    },
  • "paymentAccount":
    {
    },
  • "amount":
    {
    },
  • "createTime": "2019-07-25T14:07:45Z",
  • "updateTime": "2019-07-25T14:07:45Z",
  • "rels":
    {},
  • "operation":
    {
    }
}

Get payment operation details

Authorizations:
path Parameters
paymentId
required
string

Responses

200

OK

get /v1/payments/{paymentId}
/v1/payments/{paymentId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "status": "pending",
  • "type": "debit",
  • "merchantTransactionId": "string",
  • "description": "string",
  • "subscriptionId": "string",
  • "product":
    {
    },
  • "payer":
    {
    },
  • "paymentAccount":
    {
    },
  • "amount":
    {
    },
  • "createTime": "2019-07-25T14:07:45Z",
  • "updateTime": "2019-07-25T14:07:45Z",
  • "rels":
    {}
}

Get payment operation

Authorizations:
path Parameters
paymentId
required
string
operationId
required
string

Responses

200

OK

get /v1/payments/{paymentId}/operations/{operationId}
/v1/payments/{paymentId}/operations/{operationId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "status": "pending",
  • "operation": "payment",
  • "nextAction":
    {
    },
  • "payment":
    {
    }
}

Perform additional actions

Authorizations:
path Parameters
paymentId
required
string
operationId
required
string
Request Body schema: application/json
One of
  • PaymentAccount
  • ActionOtpRequest
paymentMethod
string

Payment method identifier

externalAccount
object

Responses

200

OK

post /v1/payments/{paymentId}/operations/{operationId}
/v1/payments/{paymentId}/operations/{operationId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "paymentMethod": "MOBIKWIK",
  • "externalAccount":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "status": "pending",
  • "operation": "payment",
  • "nextAction":
    {
    },
  • "payment":
    {
    }
}

Trigger refund operation on previous payment

Authorizations:
path Parameters
paymentId
required
string
Request Body schema: application/json
amount
object (Amount)
merchantTransactionId
string

Transaction Id set by merchant. Must be unique for this merchant

description
string

Description a user should see in their billing statement or payment processor payment page, or similar (if supported)

type
string
Value:"refund"

Responses

200

OK

500

generic failure

post /v1/payments/{paymentId}/refunds
/v1/payments/{paymentId}/refunds

Request samples

application/json
Copy
Expand all Collapse all
{
  • "amount":
    {
    },
  • "merchantTransactionId": "string",
  • "description": "string",
  • "type": "refund"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "status": "pending",
  • "type": "debit",
  • "merchantTransactionId": "string",
  • "description": "string",
  • "subscriptionId": "string",
  • "product":
    {
    },
  • "payer":
    {
    },
  • "paymentAccount":
    {
    },
  • "amount":
    {
    },
  • "createTime": "2019-07-25T14:07:45Z",
  • "updateTime": "2019-07-25T14:07:45Z",
  • "rels":
    {}
}

Get available payment methods

Authorizations:

Responses

200

OK

get /v1/paymentmethods
/v1/paymentmethods

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get payment method details

Authorizations:
path Parameters
paymentMethodId
required
string

Responses

200

OK

get /v1/paymentmethods/{paymentMethodId}
/v1/paymentmethods/{paymentMethodId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "paymentMethod": "string",
  • "enabled": true,
  • "descriptor":
    {
    }
}

Subscription API

Provides subscription management capabilities

Get registered subscriptions

Authorizations:
query Parameters
paymentId
string
limit
integer

max number of items to be returned from the collection (defaults to 10)

offset
integer

number of list items to be skipped from the collection (defaults to 0)

status
string (SubscriptionStatus)
Enum:"inactive" "active" "expired" "deactivated" "rejected" "pending"

resource status

sort
string
Enum:"createTimeAsc" "createTimeDesc" "updateTimeAsc" "updateTimeDesc"
updateTimeMax
string <date-time>
updateTimeMin
string <date-time>
createTimeMin
string <date-time>
createTimeMax
string <date-time>

Responses

200

OK

get /v1/subscriptions
/v1/subscriptions

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get subscription details

Authorizations:
path Parameters
subscriptionId
required
string

Responses

200

OK

get /v1/subscriptions/{subscriptionId}
/v1/subscriptions/{subscriptionId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "status": "inactive",
  • "plan": "string",
  • "product":
    {
    },
  • "payer":
    {
    },
  • "paymentAccount":
    {
    },
  • "createTime": "2019-07-25T14:07:45Z",
  • "updateTime": "2019-07-25T14:07:45Z",
  • "endTime": "2019-07-25T14:07:45Z",
  • "nextRenewalTime": "2019-07-25T14:07:45Z",
  • "initialPayment":
    {
    },
  • "rels":
    {},
  • "operation":
    {
    }
}

Update subscription

Authorizations:
path Parameters
subscriptionId
required
string
Request Body schem