Payment API

Overview

Introduction

This API enables an application to charge the cost of digital goods to the customer's phone bill.

Before each payment operation you want to do with your appthe customer must authorize it, giving you as a result an access token. In order to get this access token your application has to do the usual OAuth dance , but bearing in mind some differences that apply to this API:

Retrieving a request token is slightly different from the way you get a request token for other APIs since it required a few extra headers and body parameters.
When the customer authorize the request token at BlueVia Connect is not authorizing the general usage of the Payment API, but only the payment for which the request token was retrieved.
Once you have used a payment access token to make a payment, it is no longer valid for making another payment. Nevertheless you can use that access token to check the payment status for 48 hours since it was retrieved.

Making a payment

After the previous step in order to perform a payment make an authorizedPOSTrequest to https://api.bluevia.com/services/RPC/Payment/payment that will contain in the body the amount and currency of the payment. In case you want to receive a notification when the payment has been completed you’ll have to include the notification URL also in this request. The response to this call will include a payment status (that can be success, failure or pending) and a transaction id that will allow to check the payment status if the transaction is not completed.

Cancel an authorized payment

To cancel a previously authorized payment make an authorizedPOSTrequest to https://api.bluevia.com/services/RPC/Payment/cancelAuthorization including a methodCall element in the request body,formatted as XML or JSON.

Checking the payment status

There are two ways of checking the status of a payment:

Polling: Your application explicitly asks for the status of a payment.
Notifications: Your application requests to be notified about the status of a payment.

For the second mechanism please keep in mind the details about how notifications from Bluevia to the apps work (See the Authentication How to for more information).

Regardless of the method you use to check the payment status, you could get the following status information:

SUCCESS: The payment operation has been completed and the result is successful. The customer has been charged.
FAILURE: The payment operation has been completed but the result is unsuccessful. The customer has not been charged.
PENDING: The payment operation has not been completed yet. Ask again later.

Operations

The following is the description of all operations, data types and error codes related to the Payment API. Data types are formally defined in the Payment API XSD (right click to download).

· Payment
· Cancel Authorization
· Get Payment Status
· Notify Payment Final Status

Payment

Allows an application to perform a payment operation.

Request

Name	Description
URI	https://api.bluevia.com/services/RPC/Payment/payment
HTTP method	POST
Authorization	OAuth
Body	methodCall element of typeMethodCallType that will contain in the appropriate format (JSON or XML) the following data: An id element, allowing to correlate the request and the response A version element, reflecting the version of the API. A method element, indicating the operation. It is an enumerated value and for this operation it takes the value 'PAYMENT'. A timestamp element containing the time the payment is attempted. Payment details: the amount of the payment and the currency that will match the values indicatedwhen the payment request token was retrieved. Note that this amount is expressed in the minimum fractional unit of the considered currency (i.e. 100 GBP means 1,00 Pounds). Receipt request: optional parameter used to request payment status notifications. It contains the URI where your application is expecting to receive the payment status notifications. Note that BlueVia only accepts HTTPS endpoints and the server certificate must be provided during the process of requesting the API key .Besides it includes the correlator field, that has no special meaning in this API so you can left it empty

Example

Payment request using JSON format and corresponding response

POST /services/RPC/Payment/payment HTTP/1.1 Authorization: OAuth... Content-Type: application/json Host: api.bluevia.com:443  {"methodCall": {   "id": "1250",   "version": "v1",   "method": "PAYMENT",   "params": {     "paymentParams": {       "paymentInfo": {         "amount": "100",         "currency": "GBP"       },       "timestamp": "2011-06-09T09:37:53Z"     }   } }}

Response

Name

Description

HTTP status

200 OK

Body

methodResponse element of type MethodResponseType with the following information (either in JSON or XML also):

An id element, which match the id sent in the request.

A version element, reflecting the version of the API.

A transactionId element containing an identifier of the payment just done, uniquely identifying it.

A transactionStatus element indicating the status of the payment. Possible values: SUCCESS/FAILURE/PENDING.

A transactionStatusDescription element containing further information related to the above element.

SUCCESS and FAILURE are final status, i.e. the payment has been completed and the result is successful or not.PENDING status means that the payment has not been completed yet, and your application can get further information about this transaction checking the payment status.

Example

The corresponding response

A successful response consists of a 200 OK HTTP status and a methodResponse element in the response body.

HTTP/1.1 200 OK Content-Type: application/json;charset=ISO-8859-1  {"methodResponse":{   "id":"1250",   "version":"v1",   "result":{     "paymentResult":{       "transactionId":"73c1d9c55ca0b138803e3469",       "transactionStatus":"SUCCESS",       "transactionStatusDescription":"Successful Transaction"     }   } }}

Cancel Authorization

Allows an application to cancel a previously authorized payment.

Request

Name	Description
URI	https://api.bluevia.com/services/RPC/Payment/cancelAuthorization
HTTP method	POST
Authorization	OAuth
Body	methodCall element of type MethodCallType, carrying a method child element with the value 'CANCEL_AUTHORIZATION', formatted as XML or JSON and the following information: An id element, which match the id sent in the request. A version element, reflecting the version of the API.

Example

Cancel Authorization using JSON format:

POST /services/RPC/Payment/cancelAuthorization HTTP/1.1 Authorization: OAuth... Content-Type: application/json Host: api.bluevia.com:443  {"methodCall": { "id": "1265",   "version": "v1",   "method": "CANCEL_AUTHORIZATION" }}

Response

Name	Description
HTTP status	200 OK
Body	methodResponse element of type MethodResponseType, formatted as XML or JSON (same format that the request). In this case, the methodResponse element is not extended, so only the base elements are included in the response (id and version).

And the corresponding response:

HTTP/1.1 200 OK Content-Type: application/json;charset=ISO-8859-1  {"methodResponse":{   "id":"1265",   "version":"v1" }}

Get Payment Status

Allows an application to check the status of a payment operation.

Request

Name	Description
URI	https://api.bluevia.com/services/RPC/Payment/getPaymentStatus
HTTP method	POST
Authorization	OAuth
Body	methodCall element of type MethodCallType in JSON or XML with the parameters: A method element, indicating the operation. It is an enumerated value and for this operation it takes the value 'GET_PAYMENT_STATUS'. A transactionId element containing the transaction identifier returned in the response to a previous payment operation.

Example

Payment status request using JSON format:

POST /services/RPC/Payment/getPaymentStatus HTTP/1.1 Content-Type: application/json Authorization: OAuth... Host: api.bluevia.com:443  {"methodCall": {   "id": "1255",   "version": "v1",   "method": "GET_PAYMENT_STATUS",   "params": {     "getPaymentStatusParams": {       "transactionId": "928009f60b3864d969b09f90"     }   } }}

Response

Name	Description
HTTP status	200 OK
Body	methodResponse element of type MethodResponseType in JSON or XML format depending on the format of the request and carrying the following information A transactionStatus element indicating the status of the payment. A transactionStatusDescription element containing further information related to the above element.

Example

And the corresponding response:

HTTP/1.1 200 OK Content-Type: application/json;charset=ISO-8859-1  {"methodResponse":{   "id":"1255",   "version":"v1",   "result":{     "getPaymentStatusResult":{       "transactionStatus":"SUCCESS",       "transactionStatusDescription":"Successful Transaction"     }   } }}

Notify Payment Final Status

Allows BlueVia to notify your application about the final status of a payment operation.

Request

Name	Description
URI	Value included in receiptRequest.endpoint from the Paymentoperation.
HTTP method	POST
Authorization	OAuth
Body	methodCall element of type MethodCallType formatted as XML or JSON with the parameters: A method element, indicating the operation. It is an enumerated value and for this operation it takes the value 'NOTIFY_PAYMENT_FINAL_STATUS'. A transactionId element containing the transaction identifier of the payment to which this notification is related. A transactionStatus element indicating the status of the payment. A transactionStatusDescription element containing further information related to the above element.

Example

This is a payment request indicating the receipt URL that will receive the notification:

POST /services/RPC/Payment/payment HTTP/1.1 Authorization: OAuth ... Content-Type: application/xml Host: api.bluevia.com:443  {"methodCall": {     "method": "PAYMENT",      "version": "v1",      "id": "1260",      "params": {       "paymentParams": {         "receiptRequest": {           "correlator": "00023145",            "endpoint": "https://mydomain.com/myapp/receivePaymentStatus"         },          "timestamp": "2011-06-09T09:20:56Z", "paymentInfo": {           "currency": "EUR",            "amount": "177"         }       }     }   }}

And the response with the “PENDING” status:

HTTP/1.1 200 OK Content-Type: application/xml;charset=ISO-8859-1  {"methodResponse": {     "id": "1260",      "version": "v1",      "result": {       "paymentResult": {         "transactionStatusDescription": "",          "transactionId": "73a946935ca0b1383a4e4f54",          "transactionStatus": "PENDING"       }     }   }}

Once the transaction is finished Bluevia sends a request to the receipt URL indicated above:

POST /myApp/receivePaymentStatus HTTP/1.1 Authorization: OAuth...  Content-Type: application/xml  {"methodCall": {     "method": "NOTIFY_PAYMENT_FINAL_STATUS",      "version": "v1",      "id": "1260",      "params": {       "notifyPaymentFinalStatusParams": {         "transactionStatus": "SUCCESS",          "transactionId": "73a946935ca0b1383a4e4f54",          "transactionStatusDescription": "Successful Transaction"       }     }   }}

Response

Name	Description
HTTP status	200 OK
Body	methodResponse element of type MethodResponseType, formatted as XML or JSON (same format that the request).In this case the methodResponse element is not extended either, so only the base elements must be included in the response (id and version).

The response from your application with a simple 200 OK HTTP status and a methodResponse element in the response body.

HTTP/1.1 200 OK Content-Type: application/xml;charset=ISO-8859-1  {"methodResponse": {     "id": "1260",      "version": "v1"   }}

Types

MethodCallType

This type extends the base type MethodCallType defined in Common types (RPC) and has the following structure:

Name	Type	Required	Description
method	MethodType	Y	It determines the operation actually being performed.
params		N	It contains one (or none) of the following elements, which are operation dependant parameters:

Name	Type	Operation
paymentParams	PaymentParamsType	Payment
getPaymentStatusParams	GetPaymentStatusParamsType	Get Payment Status
notifyPaymentFinalStatusParams	NotifyPaymentFinalStatusParamsType	Notify Payment Final Status

MethodResponseType

This type extends the base type MethodResponseType defined in Common types (RPC) and has the following structure:

Name	Type	Required	Description
result		N	It contains one (or none) of the following elements, which are operation dependant parameters:

Name	Type	Operation
paymentResult	PaymentResultType	Payment
getPaymentStatusResult	GetPaymentStatusResultType	Get Payment Status

MethodType

This enumeration has the following values:

Value	Description
PAYMENT	Payment operation.
CANCEL_AUTHORIZATION	Cancel Authorization operation.
GET_PAYMENT_STATUS	Get Payment Status operation.
NOTIFY_PAYMENT_FINAL_STATUS	Notify Payment Final Status operation.