Whats a Prepays Payment ?
Cash in Advance/Prepayment occurs when a buyer sends payment in the agreed currency and through agreed method to a seller before the product is manufactured and/or shipped. Upon receipt of payment this seller then ships the goods and all the necessary shipping and commercial documents directly to the buyer. See more

To use Secupay Prepays Payment your contract needs to be activated for this.

Canceling Secupay prepays transaction:
When the customer won’t have the ordered product anymore you can cancel the payment transaction and the payer will get his money back if he transferred it already.

Using the secuconnect API one can:

API uses following data structures:

Supported Actions

Create secupay prepay transaction

To create new SecupayTransactionProductModel when client uses prepay, SecupayTransactionProductDTO need to be passed to PaymentSecupayPrepaysApi :: paymentSecupayprepaysPost.

Example

Create secupay prepay - shipping basket item

// Build request object
$shippingItem = new SecupayBasketItem();
$shippingItem->setItemType('shipping')
    ->setName('standard delivery')
    ->setTax('19')
    ->setTotal('1324');

Here we create a basket item of shipping type.

Create secupay prepay - article basket items

$articleItem = new SecupayBasketItem();
$articleItem->setItemType('article')
    ->setArticleNumber('3211')
    ->setQuantity('2')
    ->setName('Testname 1')
    ->setEan('4123412341243')
    ->setTax('19')
    ->setTotal('1324')
    ->setPrice('1000');
$articleItem2 = new SecupayBasketItem();
$articleItem2->setItemType('article')
    ->setArticleNumber('48875')
    ->setQuantity('2')
    ->setName('Testname 2')
    ->setEan('4123412341236')
    ->setTax('19')
    ->setTotal('1324')
    ->setPrice('1000');

Here we create two basket items of article type.

Create secupay prepay - create basket

//Please note that Basket is just ordinary array
$basket = [];
$basket[] = $shippingItem;
$basket[] = $articleItem;
$basket[] = $articleItem2;

Next we are adding items to basket. Please note that Basket is just an ordinary array.

Create secupay prepay - create ransaction DTO

$transaction = new SecupayTransactionProductDTO();
$transaction->setAmount("100")
    ->setCurrency("EUR")
    ->setOrderId("ZZZZZZ")
    ->setAccrual(True)
    ->setCustomer('PCU_XYG3DHBX32MJ8DUFASAXVA4X4M3BA2')
    ->setBasket($basket);

Finally we create SecupayTransactionProductDTO and fill fields that we need.

Creating secupay prepay transaction

// Make request
try {
	$api = new PaymentSecupayPrepaysApi();
    $response = $api->paymentSecupayprepaysPost($transaction);
    // Success. $response contain SecupayTransactionProductModel
} catch (\Secuconnect\Client\ApiException $e) {
    // 
    print_r($e->getResponseBody());
    throw $e;
}

We are making request to our API using PHP SDK on line 39 we are creating new object of PaymentSecupayPrepaysApi and then sending the request using paymentSecupayprepaysPost method to create new prepay transaction

Response format

Success

On success API will return SecupayTransactionProductModel filled in with details of transaction.

Error

If cancelation failed, $e→getResponseBody will contain ProductExceptionPayload with following possible errors:

Error	Possible reasons
ProductFormatException	no payload provided amount is missing currency is missing customer id is missing
ProductNotAllowedException	access to contract denied contract disallows transactions product id is missing api key disallows payment method
ProductDuplicateException	duplicate order_i`d`

Cancel secupay prepay transaction

To cancel transaction it's Id is required. It will be returned as id property of SecupayTransactionProductModel after successful post call.

Example

Canceling secupay prepay transaction

$transactionId = 'x...3';
 
 
// Make request
try {
	$api = new PaymentSecupayPrepaysApi();
    // $transactionId contains id of previously created transaction
    $response = $api->paymentSecupayprepaysCancelById($transactionId);
    // Success. $response body contain only confirmation.
} catch (\Secuconnect\Client\ApiException $e) {
    // Failure. $e->getResponseBody() contains ProductExceptionPayload
    print_r($e->getResponseBody());
    throw $e;
}

To cancel a prepay transaction only thing we have to do is:

to fill transactionId that we want to cancel and then call paymentSecupayprepaysCancelById method of PaymentSecupayPrepaysApi (line 8)

Response format

Success

On success API will return only confirmation.

Error

If cancelation failed, $e→getResponseBody will contain ProductExceptionPayload with following possible errors:

Error	Possible reasons
ProductNotAllowedException	access to contract denied contract id missing contract disallows payment
ProductNotFoundException	transaction not found transaction not accepted
ProductUpdateFailedException	transaction status disallows canceling transaction status change failed

Get secupay prepay transaction

Details of transaction can be retrieved by it's id.

Example

Getting secupay prepay transaction

$transactionId = 'x...3';
 
 
// Make request
try {
	$api = new PaymentSecupayPrepaysApi();
    // $transactionId contains id of existing transaction
    $response = $api->paymentSecupayprepaysGetById($transactionId);
    // Success. $response contain SecupayTransactionDTO
} catch (\Secuconnect\Client\ApiException $e) {
    // Failure. $e->getResponseBody() contains ProductExceptionPayload
    print_r($e->getResponseBody());
    throw $e;
}

To get a prepay transaction only thing we have to do is:

to fill transactionId that we want to get and then call paymentSecupayprepaysGetById method of PaymentSecupayPrepaysApi (line 8)

Response format

Success

On success API will return SecupayTransactionProductModel filled in with details of transaction.

Error

If cancelation failed, $e→getResponseBody will contain ProductExceptionPayload with following possible errors:

Error	Possible reasons
ProductNotFoundException	invalid id unknown transaction
ProductNotAllowedException	access to contract denied access to transaction denied
ProductFormatException	invalid id